{ "openapi": "3.1.0", "info": { "title": "Emerge Query API", "description": "Privacy-first API for retrieving consented user data. Query provides asynchronous and synchronous endpoints for accessing search, browsing, YouTube, ads, and receipt data.", "contact": { "name": "Emerge Support", "email": "account@emergedata.ai" }, "version": "1.27.0" }, "servers": [ { "url": "https://query.emergedata.ai", "description": "Query API - Data retrieval" } ], "paths": { "/v1/search": { "get": { "tags": [ "Query Async" ], "summary": "Search", "operationId": "search_v1_search_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "user_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "description": "User IDs to filter by (max 25)", "title": "User Ids" }, "description": "User IDs to filter by (max 25)" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end)", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end)" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "deprecated": true, "title": "Users" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" }, "examples": { "default": { "summary": "Example response", "value": { "job_id": "82f80278-5e76-4d01-8f1d-b55e08f12a52", "status": "RUNNING" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/browsing": { "get": { "tags": [ "Query Async" ], "summary": "Browsing", "operationId": "browsing_v1_browsing_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "user_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "description": "User IDs to filter by (max 25)", "title": "User Ids" }, "description": "User IDs to filter by (max 25)" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end)", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end)" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "deprecated": true, "title": "Users" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" }, "examples": { "default": { "summary": "Example response", "value": { "job_id": "82f80278-5e76-4d01-8f1d-b55e08f12a52", "status": "RUNNING" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/youtube": { "get": { "tags": [ "Query Async" ], "summary": "YouTube", "operationId": "youtube_v1_youtube_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "user_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "description": "User IDs to filter by (max 25)", "title": "User Ids" }, "description": "User IDs to filter by (max 25)" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end)", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end)" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "deprecated": true, "title": "Users" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" }, "examples": { "default": { "summary": "Example response", "value": { "job_id": "82f80278-5e76-4d01-8f1d-b55e08f12a52", "status": "RUNNING" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/ads": { "get": { "tags": [ "Query Async" ], "summary": "Ads", "operationId": "ads_v1_ads_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "user_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "description": "User IDs to filter by (max 25)", "title": "User Ids" }, "description": "User IDs to filter by (max 25)" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end)", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end)" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "deprecated": true, "title": "Users" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" }, "examples": { "default": { "summary": "Example response", "value": { "job_id": "82f80278-5e76-4d01-8f1d-b55e08f12a52", "status": "RUNNING" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/receipts": { "get": { "tags": [ "Query Async" ], "summary": "Receipts", "operationId": "receipts_v1_receipts_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "user_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "description": "User IDs to filter by (max 25)", "title": "User Ids" }, "description": "User IDs to filter by (max 25)" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end)", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end)" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, { "type": "null" } ], "deprecated": true, "title": "Users" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" }, "examples": { "default": { "summary": "Example response", "value": { "job_id": "82f80278-5e76-4d01-8f1d-b55e08f12a52", "status": "RUNNING" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/job/{task_id}": { "get": { "tags": [ "Jobs" ], "summary": "Job", "operationId": "job_v1_job__task_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryJob" }, "examples": { "default": { "summary": "Example response", "value": { "task_id": "82f80278-5e76-4d01-8f1d-b55e08f12a52", "status": "COMPLETED", "url": "https://query-results.s3.amazonaws.com/82f80278-5e76-4d01-8f1d-b55e08f12a52.parquet", "created_at": "2026-02-12T09:10:11Z", "expire_at": "2026-02-19T09:10:11Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "detail": "Job not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/jobs": { "get": { "tags": [ "Jobs" ], "summary": "Jobs", "operationId": "jobs_v1_jobs_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/QueryJob" }, "type": "array", "title": "Response Jobs V1 Jobs Get" }, "examples": { "default": { "summary": "Example response", "value": [ { "task_id": "82f80278-5e76-4d01-8f1d-b55e08f12a52", "status": "COMPLETED", "url": "https://query-results.s3.amazonaws.com/82f80278-5e76-4d01-8f1d-b55e08f12a52.parquet", "created_at": "2026-02-12T09:10:11Z", "expire_at": "2026-02-19T09:10:11Z" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "detail": "Job not found" } } } } }, "security": [ { "bearerAuth": [] } ], "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/sync/categories": { "get": { "tags": [ "Query Sync" ], "summary": "Get available categories", "description": "Return distinct category paths available for a given table.", "operationId": "get_available_categories_v1_sync_categories_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Table", "description": "Table to retrieve categories from" }, "description": "Table to retrieve categories from" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoriesResponse" }, "examples": { "default": { "summary": "Example response", "value": { "categories": [ "/Shopping/Apparel/Footwear", "/Sports/Running & Walking", "/Computers & Electronics/Software" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/sync/get_search": { "get": { "tags": [ "Query Sync" ], "summary": "Get search history (synchronous)", "description": "Returns search history data immediately using the api_search mart view.", "operationId": "endpoint_v1_sync_get_search_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end), defaults to now()", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end), defaults to now()" }, { "name": "uid", "in": "query", "required": true, "schema": { "type": "string", "description": "Your user reference", "examples": [ "alice@yourcompany.com" ], "title": "Uid" }, "description": "Your user reference" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "examples": [ "/Shopping", "/Finance/Investing" ], "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Maximum number of rows to return", "default": 1000, "title": "Limit" }, "description": "Maximum number of rows to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor from previous response", "title": "Cursor" }, "description": "Pagination cursor from previous response" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchDataResponse" }, "examples": { "default": { "summary": "Example response", "value": { "data": [ { "user_id": "psub_d4e5f6789012345678901234abcdef01", "event_id": 102938, "timestamp": "2026-02-10T08:22:11Z", "ingested_at": "2026-02-10T08:23:40Z", "url": "https://www.google.com/search?q=running+shoes", "title": "running shoes - Google Search", "query": "running shoes", "intent": "transactional", "category": "/Shopping/Apparel/Footwear", "brands": [ "Nike" ] } ], "count": 1, "next_cursor": null, "has_more": false, "applied_ingested_end": "2026-02-12T09:10:11Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "404": { "description": "User Not Found \u2013 the provided UID has no mapping for the requesting client.", "content": { "application/json": { "example": { "detail": "user_not_found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/sync/get_browsing": { "get": { "tags": [ "Query Sync" ], "summary": "Get browsing history (synchronous)", "description": "Returns browsing history data immediately using the api_browsing mart view.", "operationId": "endpoint_v1_sync_get_browsing_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end), defaults to now()", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end), defaults to now()" }, { "name": "uid", "in": "query", "required": true, "schema": { "type": "string", "description": "Your user reference", "examples": [ "alice@yourcompany.com" ], "title": "Uid" }, "description": "Your user reference" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "examples": [ "/Shopping", "/Finance/Investing" ], "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Maximum number of rows to return", "default": 1000, "title": "Limit" }, "description": "Maximum number of rows to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor from previous response", "title": "Cursor" }, "description": "Pagination cursor from previous response" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowsingDataResponse" }, "examples": { "default": { "summary": "Example response", "value": { "data": [ { "user_id": "psub_d4e5f6789012345678901234abcdef01", "event_id": 202938, "timestamp": "2026-02-10T08:30:11Z", "ingested_at": "2026-02-10T08:31:40Z", "url": "https://www.nike.com/running-shoes", "title": "Running Shoes | Nike", "page_category": "product_view", "category": "/Shopping/Apparel/Footwear", "brands": [ "Nike" ] } ], "count": 1, "next_cursor": null, "has_more": false, "applied_ingested_end": "2026-02-12T09:10:11Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "404": { "description": "User Not Found \u2013 the provided UID has no mapping for the requesting client.", "content": { "application/json": { "example": { "detail": "user_not_found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/sync/get_youtube": { "get": { "tags": [ "Query Sync" ], "summary": "Get YouTube activity (synchronous)", "description": "Returns YouTube activity data immediately using the api_youtube mart view.", "operationId": "endpoint_v1_sync_get_youtube_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end), defaults to now()", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end), defaults to now()" }, { "name": "uid", "in": "query", "required": true, "schema": { "type": "string", "description": "Your user reference", "examples": [ "alice@yourcompany.com" ], "title": "Uid" }, "description": "Your user reference" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "examples": [ "/Shopping", "/Finance/Investing" ], "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Maximum number of rows to return", "default": 1000, "title": "Limit" }, "description": "Maximum number of rows to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor from previous response", "title": "Cursor" }, "description": "Pagination cursor from previous response" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubeDataResponse" }, "examples": { "default": { "summary": "Example response", "value": { "data": [ { "user_id": "psub_d4e5f6789012345678901234abcdef01", "event_id": 302938, "timestamp": "2026-02-10T19:30:11Z", "ingested_at": "2026-02-10T19:31:40Z", "url": "https://www.youtube.com/watch?v=abc123", "title": "Best Running Shoes 2026", "category": "/Sports/Running & Walking", "brands": [ "Nike" ] } ], "count": 1, "next_cursor": null, "has_more": false, "applied_ingested_end": "2026-02-12T09:10:11Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "404": { "description": "User Not Found \u2013 the provided UID has no mapping for the requesting client.", "content": { "application/json": { "example": { "detail": "user_not_found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/sync/get_ads": { "get": { "tags": [ "Query Sync" ], "summary": "Get ad impressions (synchronous)", "description": "Returns ad impression data immediately using the api_ads mart view.", "operationId": "endpoint_v1_sync_get_ads_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end), defaults to now()", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end), defaults to now()" }, { "name": "uid", "in": "query", "required": true, "schema": { "type": "string", "description": "Your user reference", "examples": [ "alice@yourcompany.com" ], "title": "Uid" }, "description": "Your user reference" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "examples": [ "/Shopping", "/Finance/Investing" ], "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Maximum number of rows to return", "default": 1000, "title": "Limit" }, "description": "Maximum number of rows to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor from previous response", "title": "Cursor" }, "description": "Pagination cursor from previous response" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsDataResponse" }, "examples": { "default": { "summary": "Example response", "value": { "data": [ { "user_id": "psub_d4e5f6789012345678901234abcdef01", "event_id": 402938, "timestamp": "2026-02-10T09:30:11Z", "ingested_at": "2026-02-10T09:31:40Z", "source_domain": "google.com", "landing_domain": "nike.com", "url": "https://www.nike.com/running", "title": "20% Off Running Shoes", "category": "/Shopping/Apparel/Footwear", "brands": [ "Nike" ], "ad_network": "Google Ads" } ], "count": 1, "next_cursor": null, "has_more": false, "applied_ingested_end": "2026-02-12T09:10:11Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "404": { "description": "User Not Found \u2013 the provided UID has no mapping for the requesting client.", "content": { "application/json": { "example": { "detail": "user_not_found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/sync/get_receipts": { "get": { "tags": [ "Query Sync" ], "summary": "Get receipts (synchronous)", "description": "Returns receipt data immediately using the api_receipts mart view.", "operationId": "endpoint_v1_sync_get_receipts_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (start)", "title": "Begin" }, "description": "Filter by event timestamp (start)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by event timestamp (end)", "title": "End" }, "description": "Filter by event timestamp (end)" }, { "name": "ingested_begin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (start)", "title": "Ingested Begin" }, "description": "Filter by ingestion timestamp (start)" }, { "name": "ingested_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by ingestion timestamp (end), defaults to now()", "title": "Ingested End" }, "description": "Filter by ingestion timestamp (end), defaults to now()" }, { "name": "uid", "in": "query", "required": true, "schema": { "type": "string", "description": "Your user reference", "examples": [ "alice@yourcompany.com" ], "title": "Uid" }, "description": "Your user reference" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category subtree to filter by", "examples": [ "/Shopping", "/Finance/Investing" ], "title": "Category" }, "description": "Category subtree to filter by" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Maximum number of rows to return", "default": 1000, "title": "Limit" }, "description": "Maximum number of rows to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor from previous response", "title": "Cursor" }, "description": "Pagination cursor from previous response" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptsDataResponse" }, "examples": { "default": { "summary": "Example response", "value": { "data": [ { "user_id": "psub_d4e5f6789012345678901234abcdef01", "event_id": 502938, "timestamp": "2026-02-09T11:10:11Z", "ingested_at": "2026-02-09T11:12:00Z", "subject": "Your receipt from Nike", "retailer_name": "Nike", "receipt_currency": "USD", "total_value": 129.99, "items": [ { "name": "Nike Pegasus 42", "quantity": 1, "price": 129.99, "brand": "Nike", "category": "/Shopping/Apparel/Footwear" } ], "category": "/Shopping/Apparel/Footwear", "brands": [ "Nike" ] } ], "count": 1, "next_cursor": null, "has_more": false, "applied_ingested_end": "2026-02-12T09:10:11Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "detail": "Invalid token" } } } }, "404": { "description": "User Not Found \u2013 the provided UID has no mapping for the requesting client.", "content": { "application/json": { "example": { "detail": "user_not_found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mint": { "server": "https://query.emergedata.ai" } } }, "/v1/graphql": { "get": { "tags": [ "GraphQL" ], "summary": "Handle Http Get", "operationId": "handle_http_get_v1_graphql_get", "responses": { "200": { "description": "The GraphiQL integrated development environment.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found if GraphiQL or query via GET are not enabled." } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "GraphQL" ], "summary": "Handle Http Post", "operationId": "handle_http_post_v1_graphql_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "AdsDataResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdsEvent" }, "type": "array", "title": "Data" }, "count": { "type": "integer", "title": "Count" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "has_more": { "type": "boolean", "title": "Has More" }, "applied_ingested_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Applied Ingested End" } }, "type": "object", "title": "AdsDataResponse" }, "AdsEvent": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "event_id": { "type": "integer", "title": "Event Id" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp" }, "ingested_at": { "type": "string", "format": "date-time", "title": "Ingested At" }, "source_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Domain" }, "landing_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Landing Domain" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "brands": { "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "array", "title": "Brands" }, "ad_network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ad Network" } }, "type": "object", "title": "AdsEvent" }, "BrowsingDataResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BrowsingEvent" }, "type": "array", "title": "Data" }, "count": { "type": "integer", "title": "Count" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "has_more": { "type": "boolean", "title": "Has More" }, "applied_ingested_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Applied Ingested End" } }, "type": "object", "title": "BrowsingDataResponse" }, "BrowsingEvent": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "event_id": { "type": "integer", "title": "Event Id" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp" }, "ingested_at": { "type": "string", "format": "date-time", "title": "Ingested At" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "page_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Category" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands" } }, "type": "object", "title": "BrowsingEvent" }, "CategoriesResponse": { "properties": { "categories": { "items": { "type": "string" }, "type": "array", "title": "Categories" } }, "type": "object", "title": "CategoriesResponse" }, "CreateJobResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "status": { "$ref": "#/components/schemas/JobStatus" } }, "type": "object", "title": "CreateJobResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "JobStatus": { "type": "string", "enum": [ "RUNNING", "COMPLETED", "FAILED" ], "title": "JobStatus" }, "QueryJob": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "expire_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expire At" } }, "type": "object", "title": "QueryJob" }, "ReceiptItem": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Quantity" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Price" }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, "type": "object", "title": "ReceiptItem" }, "ReceiptsDataResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ReceiptsEvent" }, "type": "array", "title": "Data" }, "count": { "type": "integer", "title": "Count" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "has_more": { "type": "boolean", "title": "Has More" }, "applied_ingested_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Applied Ingested End" } }, "type": "object", "title": "ReceiptsDataResponse" }, "ReceiptsEvent": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "event_id": { "type": "integer", "title": "Event Id" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp" }, "ingested_at": { "type": "string", "format": "date-time", "title": "Ingested At" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "retailer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer Name" }, "receipt_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Receipt Currency" }, "total_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Value" }, "items": { "items": { "$ref": "#/components/schemas/ReceiptItem" }, "type": "array", "title": "Items" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "brands": { "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "array", "title": "Brands" } }, "type": "object", "title": "ReceiptsEvent" }, "SearchDataResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SearchEvent" }, "type": "array", "title": "Data" }, "count": { "type": "integer", "title": "Count" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "has_more": { "type": "boolean", "title": "Has More" }, "applied_ingested_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Applied Ingested End" } }, "type": "object", "title": "SearchDataResponse" }, "SearchEvent": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "event_id": { "type": "integer", "title": "Event Id" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp" }, "ingested_at": { "type": "string", "format": "date-time", "title": "Ingested At" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query" }, "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Intent" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands" } }, "type": "object", "title": "SearchEvent" }, "Table": { "type": "string", "enum": [ "ads", "searches", "browsing", "youtube", "receipts" ], "title": "Table" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "title": "ValidationError" }, "YouTubeDataResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/YouTubeEvent" }, "type": "array", "title": "Data" }, "count": { "type": "integer", "title": "Count" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "has_more": { "type": "boolean", "title": "Has More" }, "applied_ingested_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Applied Ingested End" } }, "type": "object", "title": "YouTubeDataResponse" }, "YouTubeEvent": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "event_id": { "type": "integer", "title": "Event Id" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp" }, "ingested_at": { "type": "string", "format": "date-time", "title": "Ingested At" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands" } }, "type": "object", "title": "YouTubeEvent" } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "API token from the Control Room. Include as `Authorization: Bearer `", "scheme": "bearer" } } }, "tags": [ { "name": "Query Async", "description": "Asynchronous data queries with job polling" }, { "name": "Query Sync", "description": "Synchronous data queries with immediate response" }, { "name": "Jobs", "description": "Job status and management" } ] }