{"openapi":"3.1.0","info":{"title":"Conductor Data API","description":"## API Gateway Usage\nAll API requests must be made to the API Gateway URL (check Servers section below), not directly to the Data API.\nThe API Gateway handles authentication, rate limiting, and routing to the appropriate backend services.\n\n\n## Authentication\nThe Data API requires secure authentication for all requests. Authentication is handled through the API Gateway using an API key and request signature system that ensures secure access to the data.\n\n<details>\n<summary><b>Authentication with API key and signature</b></summary>\n\nAll endpoints require authentication through the API Gateway using ALL of the following elements together:\n\n1. API Key as a query parameter: `apiKey=<your-api-key>`\n2. Request signature as a query parameter: `sig=<computed-signature>`\n\nThe signature is computed using your API key and secret. Example Python code for computing the signature:\n\n```python\nimport hashlib\nimport time\n\ndef compute_signature(api_key: str, secret: str) -> str:\n    # Create the string to sign (api_key + secret + timestamp)\n    timestamp = str(int(time.time()))  # Unix timestamp in seconds\n    string_to_sign = f\"{api_key}{secret}{timestamp}\"\n    # Compute MD5 signature\n    signature = hashlib.md5(string_to_sign.encode('utf-8')).hexdigest()\n    return signature\n\n# Example usage:\napi_key = \"your-api-key\"\nsecret = \"your-secret\"\nsignature = compute_signature(api_key, secret)\n\nurl = f\"https://api-universal.conductor.com/data-api/v1/keyword_rankings?apiKey={api_key}&sig={signature}\"\n```\n</details>\n\n\n## Asynchronous Queries\nThe Data API supports asynchronous query execution for potentially long-running queries.\nThis allows clients to submit a query and retrieve results later, rather than waiting for the entire query to complete.\nAsynchronous endpoints are marked with **(Async)** in their descriptions.\n\n<details>\n<summary><b>Asynchronous Query Details</b></summary>\n\n#### Asynchronous Query Flow\n1. **Initial Request**: Submit query parameters - returns 202 Accepted with `executionId`\n2. **Polling**: Use `executionId` to poll for results - returns 200 OK when complete or 202 Accepted if still running\n3. **Pagination**: Use `nextPageId` from completed results to get additional pages\n\n#### Request Parameters\n- For initial submission: Include all required query parameters specific to the endpoint\n- For polling: Include `executionId` (and optionally `pageSize`, `nextPageId` for pagination)\n\n#### Response Fields\n- `executionId` Unique identifier for tracking the query execution\n- `executionState` Status of the query (\"IN_PROGRESS\" or \"COMPLETED\")\n- `nextPageId` Token for retrieving the next page of results when available\n\n#### Response Codes\n- **202 Accepted**: Query is still running (executionState = \"IN_PROGRESS\")\n- **200 OK**: Query completed successfully (executionState = \"COMPLETED\")\n</details>\n","contact":{"name":"Data Platform Team","email":"data-platform@conductor.com"},"version":"1.0.0"},"servers":[{"url":"https://api-universal.conductor.com"}],"security":[{"ApiKeyQuery":[],"SigQuery":[]}],"tags":[{"name":"Traditional Search / Foundational","description":"Core keyword ranking and SERP data from traditional search engines"},{"name":"Traditional Search / Derived","description":"Derived metrics from traditional search data, such as highest ranking URL per keyword"},{"name":"AI / Foundational","description":"Foundational data from AI search engines including brand mentions, citations, and sentiment analysis"}],"paths":{"/data-api/v1/async/keyword_rankings":{"post":{"tags":["Traditional Search / Foundational"],"summary":"Query Keyword Rankings (Async)","description":"Execute an asynchronous query against the keyword rankings dataset to get detailed SERP information.\nThis endpoint follows the asynchronous query flow.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryKeywordRankings","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/KeywordRankingsRequest"}],"description":"Submit a new query with filters and parameters. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking the query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and a `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]}}},"required":true},"responses":{"200":{"description":"Query completed successfully (returned when polling with queryExecutionId)","content":{"application/json":{"schema":{"type":"object","example":{"results":[["123","Example Account","DF3DAF2955754FDDB180CF505AE4761E","Example Organization","456","conductor.com","2025-01-01","2025-01-07","2025-01-05","GOOGLE_EN_US","GOOGLE","US","en","US","DESKTOP","best smartphones 2025","Best Smartphones 2025 - Complete Guide","https://example.com/best-smartphones-2025","example.com","www.example.com","STANDARD_LINK","1","1","1","12, 45, 78","Brand, Non-Brand, Category","12000","1.25","0.75","10000","202501"]],"schema":[{"name":"account_id","type":"integer"},{"name":"account_name","type":"string"},{"name":"organization_id","type":"string"},{"name":"organization_name","type":"string"},{"name":"web_property_id","type":"integer"},{"name":"web_property_name","type":"string"},{"name":"time_period_start","type":"date"},{"name":"time_period_end","type":"date"},{"name":"collection_date","type":"date"},{"name":"search_engine_name","type":"string"},{"name":"search_engine","type":"string"},{"name":"search_engine_country_code","type":"string"},{"name":"search_engine_language_code","type":"string"},{"name":"locode","type":"string"},{"name":"device","type":"string"},{"name":"query","type":"string"},{"name":"title","type":"string"},{"name":"normalized_url","type":"string"},{"name":"root_domain","type":"string"},{"name":"subdomain","type":"string"},{"name":"result_type","type":"string"},{"name":"rank_standard","type":"integer"},{"name":"rank_true","type":"integer"},{"name":"rank_result_type","type":"integer"},{"name":"keyword_group_ids","type":"string"},{"name":"keyword_group_names","type":"string"},{"name":"average_search_volume","type":"integer"},{"name":"cpc","type":"float"},{"name":"competition","type":"float"},{"name":"approximate_search_volume","type":"integer"},{"name":"msv_month","type":"integer"}],"executionState":"COMPLETED","executionId":"ath:abc123","requestId":"req-123","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\n","items":{"$ref":"#/components/schemas/KeywordRankingRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:b3d8a1c7-9f2e-4d6a-a5b1-8c4e2f7d9a03","requestId":"4e2c8f19-7a3d-4b5e-9c1f-6d8a2e4b7f30"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","example":{"error":"INVALID_PARAMETERS","message":"start_date must be before end_date"},"properties":{"error":{"type":"string","description":"Error code or identifier"},"message":{"type":"string","description":"Detailed error message"}}}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}},"/data-api/v1/async/highest_ranking_url_per_keyword":{"post":{"tags":["Traditional Search / Derived"],"summary":"Query Highest Ranking URLs per Keyword (Async)","description":"Execute an asynchronous query against the keyword rankings dataset to get highest ranking URL per keyword.\nThis endpoint follows the asynchronous query flow.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryHighestRankingUrlPerKeyword","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/HighestRankingUrlPerKeywordRequest"}],"description":"Submit a new query with filters and parameters. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking the query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and a `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]}}},"required":true},"responses":{"200":{"description":"Query completed successfully (returned when polling with queryExecutionId)","content":{"application/json":{"schema":{"type":"object","example":{"results":[["123","Example Account","DF3DAF2955754FDDB180CF505AE4761E","Example Organization","456","conductor.com","2025-01-01","2025-01-07","2025-01-05","GOOGLE_EN_US","GOOGLE","US","en","US","DESKTOP","best smartphones 2025","Best Smartphones 2025 - Complete Guide","https://example.com/best-smartphones-2025","example.com","www.example.com","STANDARD_LINK","1","1","1","12,45,78","Brand,Non-Brand,Category","12000","1.25","0.75","10000","202506"]],"schema":[{"name":"account_id","type":"integer"},{"name":"account_name","type":"string"},{"name":"organization_id","type":"string"},{"name":"organization_name","type":"string"},{"name":"web_property_id","type":"integer"},{"name":"web_property_name","type":"string"},{"name":"time_period_start","type":"date"},{"name":"time_period_end","type":"date"},{"name":"collection_date","type":"date"},{"name":"search_engine_name","type":"string"},{"name":"search_engine","type":"string"},{"name":"search_engine_country_code","type":"string"},{"name":"search_engine_language_code","type":"string"},{"name":"locode","type":"string"},{"name":"device","type":"string"},{"name":"query","type":"string"},{"name":"title","type":"string"},{"name":"normalized_url","type":"string"},{"name":"root_domain","type":"string"},{"name":"subdomain","type":"string"},{"name":"result_type","type":"string"},{"name":"rank_standard","type":"integer"},{"name":"rank_true","type":"integer"},{"name":"rank_result_type","type":"integer"},{"name":"keyword_group_ids","type":"string"},{"name":"keyword_group_names","type":"string"},{"name":"average_search_volume","type":"integer"},{"name":"cpc","type":"float"},{"name":"competition","type":"float"},{"name":"approximate_search_volume","type":"integer"},{"name":"msv_month","type":"integer"}],"executionState":"COMPLETED","executionId":"ath:abc123","requestId":"req-123","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\n","items":{"$ref":"#/components/schemas/HighestRankingUrlPerKeywordRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:c4e9b2d8-a03f-4e7b-b6c2-9d5f3a8e1b04","requestId":"5f3d9a20-8b4e-4c6f-ad2a-7e9b3f5c8a41"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","example":{"error":"INVALID_PARAMETERS","message":"start_date must be before end_date"},"properties":{"error":{"type":"string","description":"Error code or identifier"},"message":{"type":"string","description":"Detailed error message"}}}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}},"/data-api/v1/async/ai_search_brands":{"post":{"tags":["AI / Foundational"],"summary":"Query AI Search Brand Data (Async)","description":"Execute a query to retrieve brand-focused data from AI search responses, including only own brand entities.\nThis endpoint follows the asynchronous query flow.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryAiSearchBrandsAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/AiSearchBrandsRequest"}],"description":"Submit a new query with filters and parameters. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking the query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and a `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]}}},"required":true},"responses":{"200":{"description":"Successful query execution","content":{"application/json":{"schema":{"type":"object","example":{"results":[["Conductor Organization","base64-encoded-organization-id","Conductor Account","123","conductor.com","456","2026-01-11","2026-01-17","WEEKLY","US","en_US","chatgpt","best AEO and GEO platforms","best AEO and GEO platforms 2026 - complete guide","unbranded","Educational","broad audience","Conductor","brand","you","true","true"]],"schema":[{"name":"organization_name","type":"string"},{"name":"organization_id","type":"string"},{"name":"account_name","type":"string"},{"name":"account_id","type":"integer"},{"name":"web_property_name","type":"string"},{"name":"web_property_id","type":"integer"},{"name":"time_period_start","type":"date"},{"name":"time_period_end","type":"date"},{"name":"collection_frequency","type":"string"},{"name":"locode","type":"string"},{"name":"language","type":"string"},{"name":"ai_search_engine","type":"string"},{"name":"topic","type":"string"},{"name":"prompt","type":"string"},{"name":"prompt_type","type":"string"},{"name":"intent","type":"string"},{"name":"persona","type":"string"},{"name":"brand_or_product_name","type":"string"},{"name":"brand_or_product_entity_type","type":"string"},{"name":"brand_or_product_attribution","type":"string"},{"name":"ai_response_collected","type":"boolean"},{"name":"web_search_triggered","type":"boolean"}],"executionState":"COMPLETED","executionId":"enga:f47ac10b-58cc-4372-a567-0e02b2c3d479","requestId":"9e3b7c12-f4a5-48d1-b6e9-0c32d5a8e1b4","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\n","items":{"$ref":"#/components/schemas/AiSearchBrandsRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:d5fa3c9e-b14a-4f8c-c7d3-ae6a4b9f2c15","requestId":"6a4eab31-9c5f-4d7a-be3b-8fab4a6d9b52"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","example":{"error":"INVALID_PARAMETERS","message":"start_date must be before end_date"},"properties":{"error":{"type":"string","description":"Error code or identifier"},"message":{"type":"string","description":"Detailed error message"}}}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}},"/data-api/v1/async/ai_search_citations":{"post":{"tags":["AI / Foundational"],"summary":"Query AI Search Citations Data (Async)","description":"Execute a query to retrieve citation-focused data from AI search responses.\nThis endpoint follows the asynchronous query flow.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryAiSearchCitationsAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/AiSearchCitationsRequest"}],"description":"Submit a new query with filters and parameters. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking the query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and a `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]}}},"required":true},"responses":{"200":{"description":"Query completed successfully","content":{"application/json":{"schema":{"type":"object","example":{"results":[["Conductor Organization","base64-encoded-organization-id","Conductor Account","123","conductor.com","456","2026-01-11","2026-01-17","WEEKLY","US","en_US","chatgpt","best AEO and GEO platforms","best AEO and GEO platforms 2026 - complete guide","unbranded","Educational","broad audience","Conductor | The Leading Organic Marketing Platform","https://www.conductor.com/","conductor.com","blog.conductor.com","you","true","true"]],"schema":[{"name":"organization_name","type":"string"},{"name":"organization_id","type":"string"},{"name":"account_name","type":"string"},{"name":"account_id","type":"integer"},{"name":"web_property_name","type":"string"},{"name":"web_property_id","type":"integer"},{"name":"time_period_start","type":"date"},{"name":"time_period_end","type":"date"},{"name":"collection_frequency","type":"string"},{"name":"locode","type":"string"},{"name":"language","type":"string"},{"name":"ai_search_engine","type":"string"},{"name":"topic","type":"string"},{"name":"prompt","type":"string"},{"name":"prompt_type","type":"string"},{"name":"intent","type":"string"},{"name":"persona","type":"string"},{"name":"citation_title","type":"string"},{"name":"citation_url","type":"string"},{"name":"citation_domain","type":"string"},{"name":"citation_web_property_segment","type":"string"},{"name":"citation_attribution","type":"string"},{"name":"ai_response_collected","type":"boolean"},{"name":"web_search_triggered","type":"boolean"}],"executionState":"COMPLETED","executionId":"enga:f47ac10b-58cc-4372-a567-0e02b2c3d479","requestId":"9e3b7c12-f4a5-48d1-b6e9-0c32d5a8e1b4","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\n","items":{"$ref":"#/components/schemas/AiSearchCitationsRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:e6ab4daf-c25b-4a9d-d8e4-bf7b5caa3d26","requestId":"7b5fbc42-ad6a-4e8b-cf4c-9abc5b7eac63"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","example":{"error":"INVALID_PARAMETERS","message":"start_date must be before end_date"},"properties":{"error":{"type":"string","description":"Error code or identifier"},"message":{"type":"string","description":"Detailed error message"}}}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}},"/data-api/v1/async/ai_search_sentiments":{"post":{"tags":["AI / Foundational"],"summary":"Query AI Search Sentiments Data (Async)","description":"Execute a query to retrieve brand sentiments extracted from AI search responses.\nEach row represents a single sentiment mention for a brand within an AI response, including optional snippet and its source.\nThis endpoint follows the asynchronous query flow.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryAiSearchSentimentsAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/AiSearchSentimentsRequest"}],"description":"Submit a new query with filters and parameters. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking the query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and a `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]}}},"required":true},"responses":{"200":{"description":"Query completed successfully","content":{"application/json":{"schema":{"type":"object","example":{"results":[["Example Organization","DF3DAF2955754FDDB180CF505AE4761E","Example Account","123","conductor.com","456","2024-03-01","2024-03-15","WEEKLY","US-NYC","en_US","chatgptsearch","marketing automation","best marketing automation tools","branded","commercial","Marketing Manager","Conductor","positive","10","pricing","Conductor offers intuitive tools that simplify SEO workflows.","https://example.com/review","example.com","true","false"]],"schema":[{"name":"organization_name","type":"string"},{"name":"organization_id","type":"string"},{"name":"account_name","type":"string"},{"name":"account_id","type":"integer"},{"name":"web_property_name","type":"string"},{"name":"web_property_id","type":"integer"},{"name":"time_period_start","type":"date"},{"name":"time_period_end","type":"date"},{"name":"collection_frequency","type":"string"},{"name":"locode","type":"string"},{"name":"language","type":"string"},{"name":"ai_search_engine","type":"string"},{"name":"topic","type":"string"},{"name":"prompt","type":"string"},{"name":"prompt_type","type":"string"},{"name":"intent","type":"string"},{"name":"persona","type":"string"},{"name":"sentiment_brand","type":"string"},{"name":"sentiment_value","type":"string"},{"name":"sentiment_score","type":"float"},{"name":"sentiment_category","type":"string"},{"name":"sentiment_snippet","type":"string"},{"name":"sentiment_source_url","type":"string"},{"name":"sentiment_source_domain","type":"string"},{"name":"ai_response_collected","type":"boolean"},{"name":"web_search_triggered","type":"boolean"}],"executionState":"COMPLETED","executionId":"ath:abc123","requestId":"req-123","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\n","items":{"$ref":"#/components/schemas/AiSearchSentimentsRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:f7bc5eba-d36c-4bae-e9f5-ca8c6dbb4e37","requestId":"8c6acd53-be7b-4f9c-da5d-abcd6c8fbd74"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","example":{"error":"INVALID_PARAMETERS","message":"start_date must be before end_date"},"properties":{"error":{"type":"string","description":"Error code or identifier"},"message":{"type":"string","description":"Detailed error message"}}}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}},"/data-api/v1/async/ai_search_response":{"post":{"tags":["AI / Foundational"],"summary":"Query AI Search Response Data (Async)","description":"Execute a query to retrieve response-focused data from AI search responses.\nThis endpoint follows the asynchronous query flow.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryAiSearchResponseAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/AiSearchResponseRequest"}],"description":"Submit a new query with filters and parameters. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking the query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and a `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]}}},"required":true},"responses":{"200":{"description":"Query completed successfully","content":{"application/json":{"schema":{"type":"object","example":{"results":[["Conductor Organization","base64-encoded-organization-id","Conductor Account","123","conductor.com","456","WEEKLY","2026-01-11","2026-01-17","US","en_US","engine-123","chatgptsearch","marketing automation","best AEO and GEO platforms","commercial","Marketing Manager","Here are some of the best marketing automation tools available...","2024-03-15"]],"schema":[{"name":"organization_name","type":"string"},{"name":"organization_id","type":"string"},{"name":"account_name","type":"string"},{"name":"account_id","type":"integer"},{"name":"web_property_name","type":"string"},{"name":"web_property_id","type":"integer"},{"name":"collection_frequency","type":"string"},{"name":"time_period_start","type":"date"},{"name":"time_period_end","type":"date"},{"name":"locode","type":"string"},{"name":"language","type":"string"},{"name":"ai_search_engine_id","type":"string"},{"name":"ai_search_engine","type":"string"},{"name":"topic","type":"string"},{"name":"prompt","type":"string"},{"name":"intent","type":"string"},{"name":"persona","type":"string"},{"name":"ai_response","type":"string"},{"name":"collection_date","type":"date"}],"executionState":"COMPLETED","executionId":"enga:f47ac10b-58cc-4372-a567-0e02b2c3d479","requestId":"9e3b7c12-f4a5-48d1-b6e9-0c32d5a8e1b4","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\n","items":{"$ref":"#/components/schemas/AiSearchResponseRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:d5fa3c9e-b14a-4f8c-c7d3-ae6a4b9f2c15","requestId":"6a4eab31-9c5f-4d7a-be3b-8fab4a6d9b52"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}},"/data-api/v1/async/web_properties_config":{"post":{"tags":["Configuration"],"summary":"Query Web Properties Configuration (Async)","description":"\nExecute an asynchronous query against the web properties config dataset to get \nowned web properties. This endpoint follows the asynchronous query flow.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryWebPropertiesConfigAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/WebPropertiesConfigRequest"}],"description":"Submit a new query for web properties. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]},"examples":{"web_properties":{"summary":"Get web properties for account","value":{"account_id":101}}}}},"required":true},"responses":{"200":{"description":"Query completed successfully (returned when polling with queryExecutionId)","content":{"application/json":{"schema":{"type":"object","example":{"results":[["456","conductor.com","[conductor.com]"]],"schema":[{"name":"web_property_id","type":"string"},{"name":"web_property_name","type":"string"},{"name":"root_domains","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444444","requestId":"req-123","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\n","items":{"$ref":"#/components/schemas/WebPropertiesConfigRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:b3d8a1c7-9f2e-4d6a-a5b1-8c4e2f7d9a03","requestId":"4e2c8f19-7a3d-4b5e-9c1f-6d8a2e4b7f30"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","example":{"error":"INVALID_PARAMETERS","message":"account_id must be provided"},"properties":{"error":{"type":"string","description":"Error code or identifier"},"message":{"type":"string","description":"Detailed error message"}}}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}},"/data-api/v1/async/comparison_web_properties_config":{"post":{"tags":["Configuration"],"summary":"Query Comparison Web Properties Configuration (Async)","description":"Execute an asynchronous query against the comparison web properties config dataset to get \ncomparison web properties having associated owned web properties. This endpoint follows the asynchronous query flow.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryComparisonWebPropertiesConfigAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/ComparisonWebPropertiesConfigRequest"}],"description":"Submit a new query for comparison web properties. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]},"examples":{"comparison_web_properties":{"summary":"Get comparison web properties for account","value":{"account_id":101}}}}},"required":true},"responses":{"200":{"description":"Query completed successfully (returned when polling with queryExecutionId)","content":{"application/json":{"schema":{"type":"object","example":{"results":[["456","conductor.com","Business Competitor","[conductor.com]","[conductor.com (GOOGLE_EN_US)]"]],"schema":[{"name":"web_property_id","type":"string"},{"name":"web_property_name","type":"string"},{"name":"attribution_label","type":"string"},{"name":"root_domains","type":"string"},{"name":"compared_against","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444444","requestId":"req-123","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\n","items":{"$ref":"#/components/schemas/ComparisonWebPropertiesConfigRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:b3d8a1c7-9f2e-4d6a-a5b1-8c4e2f7d9a03","requestId":"4e2c8f19-7a3d-4b5e-9c1f-6d8a2e4b7f30"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","example":{"error":"INVALID_PARAMETERS","message":"account_id must be provided"},"properties":{"error":{"type":"string","description":"Error code or identifier"},"message":{"type":"string","description":"Detailed error message"}}}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}},"/data-api/v1/async/keyword_search_config":{"post":{"tags":["Configuration","Traditional"],"summary":"Query Keyword Configuration (Async)","description":"Execute an asynchronous query against keyword tracking configuration metadata.\nThe response schema varies based on the `config_type` parameter.\nThis endpoint follows the asynchronous query flow.\n\n### Config Types:\n- **`keywords`**: Tracked keywords with status, groups, locale, search engine, and device. Supports optional filters: `web_property_id`, `keyword_group_id`, `keyword_status`.\n- **`keyword_groups`**: Keyword groups defined for the account.\n- **`search_engines`**: Distinct search engines in use for tracked keywords.\n- **`devices`**: Distinct devices in use for tracked keywords.\n- **`locales`**: Distinct locales in use for tracked keywords.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryKeywordSearchConfigAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/KeywordSearchConfigRequest"}],"description":"Submit a new keyword config query. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]},"examples":{"keywords":{"summary":"Get tracked keywords for account","value":{"config_type":"keywords","account_id":101,"web_property_id":456,"keyword_status":"ACTIVE","keyword_group_id":"995895","limit":100}},"keyword_groups":{"summary":"Get keyword groups for account","value":{"config_type":"keyword_groups","account_id":101}},"search_engines":{"summary":"Get keyword search engines in use","value":{"config_type":"search_engines","account_id":101}},"devices":{"summary":"Get devices in use","value":{"config_type":"devices","account_id":101}},"locales":{"summary":"Get locales used by tracked keywords","value":{"config_type":"locales","account_id":101}}}}},"required":true},"responses":{"200":{"description":"Query completed successfully (returned when polling with queryExecutionId).\nThe response `schema` and `results` tuple structure vary by `config_type` — see Config Types above.\nThe default schema example below shows the `keywords` config_type response.\nNamed 200 response examples are also provided for each supported `config_type`.\n","content":{"application/json":{"schema":{"type":"object","example":{"results":[["456","best seo practices 2025","ACTIVE","[Brand, Non-Brand]","2025-01-01","US","GOOGLE_EN_US","Desktop"]],"schema":[{"name":"web_property_id","type":"string"},{"name":"keyword","type":"string"},{"name":"status","type":"string"},{"name":"keyword_groups","type":"string"},{"name":"tracking_start_date","type":"date"},{"name":"locale","type":"string"},{"name":"kw_search_engine","type":"string"},{"name":"device","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444444","requestId":"req-123","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\nColumn order depends on `config_type` — use the `schema` field to interpret positions.\n","items":{"$ref":"#/components/schemas/KeywordSearchConfigRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}},"examples":{"keywords":{"summary":"Tracked keywords response","value":{"results":[["456","best seo practices 2025","ACTIVE","[Brand, Non-Brand]","2025-01-01","US","GOOGLE_EN_US","Desktop"]],"schema":[{"name":"web_property_id","type":"string"},{"name":"keyword","type":"string"},{"name":"status","type":"string"},{"name":"keyword_groups","type":"string"},{"name":"tracking_start_date","type":"date"},{"name":"locale","type":"string"},{"name":"kw_search_engine","type":"string"},{"name":"device","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444444","requestId":"req-123","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000}},"keyword_groups":{"summary":"Keyword groups response","value":{"results":[["995895","Brand"],["995896","Non-Brand"]],"schema":[{"name":"keyword_group_id","type":"string"},{"name":"keyword_group_name","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444445","requestId":"req-124","totalRowCount":2}},"search_engines":{"summary":"Search engines response","value":{"results":[["GOOGLE_EN_US"],["BING_EN_US"]],"schema":[{"name":"name","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444446","requestId":"req-125","totalRowCount":2}},"devices":{"summary":"Devices response","value":{"results":[["Desktop"],["Mobile"]],"schema":[{"name":"name","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444447","requestId":"req-126","totalRowCount":2}},"locales":{"summary":"Locales response","value":{"results":[["US"],["US-NYC"]],"schema":[{"name":"locode","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444448","requestId":"req-127","totalRowCount":2}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:b3d8a1c7-9f2e-4d6a-a5b1-8c4e2f7d9a03","requestId":"4e2c8f19-7a3d-4b5e-9c1f-6d8a2e4b7f30"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","example":{"error":"INVALID_PARAMETERS","message":"config_type must be one of: keywords, keyword_groups, search_engines, devices, locales"},"properties":{"error":{"type":"string","description":"Error code or identifier"},"message":{"type":"string","description":"Detailed error message"}}}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}},"/data-api/v1/async/ai_search_config":{"post":{"tags":["Configuration","AI Search"],"summary":"Query AI Search Configuration (Async)","description":"Execute an asynchronous query against AI search configuration metadata.\nThe response schema varies based on the `config_type` parameter.\nThis endpoint follows the asynchronous query flow.\n\n### Config Types:\n- **`topics`**: Tracked AI search topics with status, search engine, frequency, locale, and prompt count. Supports optional filters: `topic_status`, `prompt_status`.\n- **`prompts`**: Individual prompts with type, status, topic, search engine, locale, language, intent, and persona. Supports optional filters: `topic_status`, `prompt_status`, `topics`.\n- **`search_engines`**: Distinct AI search engines in use for tracked topics.\n- **`locales`**: Distinct locales in use for tracked topics.\n- **`languages`**: Distinct languages in use for tracked topics.\n- **`brands`**: Tracked brands with associated owned and comparison web properties.\n- **`personas`**: Personas defined for the account.\n- **`intents`**: Distinct intents in use for tracked prompts.\n- **`sentiment_categories`**: Distinct sentiment categories observed in AI search results.\n\n### Usage Patterns:\n- **Submit**: Create a query (Initial request). Returns `executionId`.\n- **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`.\n- **Paginate**: Use `executionId` and `nextPageId` from the previous response.\n\n### Rate Limits:\n- **Submit**: 40 req/min (Hard), 5 req/min (Recommended).\n- **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended).\n\n### Sequential Pagination:\n- Pagination must be performed sequentially. Each request for the next page must use the `nextPageId` returned in the previous response. Parallel pagination is not supported.\n","operationId":"queryAiSearchConfigAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/AiSearchConfigRequest"}],"description":"Submit a new AI search config query. Returns an `executionId` to track the query.","title":"Submit"},{"type":"object","description":"Poll for the status of a previously submitted query using its `executionId`.","properties":{"executionId":{"type":"string","description":"Unique execution identifier for tracking query status. Valid for 7 days."}},"required":["executionId"],"title":"Poll"},{"type":"object","description":"Retrieve more results for a completed query using its `executionId` and `nextPageId` token.\nNote: Pagination must be done sequentially as `nextPageId` depends on the current page.\n","properties":{"executionId":{"type":"string","description":"Unique execution identifier. Valid for 7 days."},"nextPageId":{"type":"string","description":"Token to retrieve the next page of results. Available for 7 days."},"pageSize":{"type":"integer","description":"The number of results to return per page.\nMaximum: 1000. Default: 1000.\n","maximum":1000,"minimum":1}},"required":["executionId","nextPageId"],"title":"Paginate"}]},"examples":{"topics":{"summary":"Get topics for account","value":{"config_type":"topics","account_id":101,"topic_status":"ACTIVE","prompt_status":"ACTIVE"}},"prompts":{"summary":"Get prompts with topic info for account","value":{"config_type":"prompts","account_id":101,"topic_status":"ACTIVE","prompt_status":"ACTIVE","topics":"ai search,seo tools","limit":100}},"search_engines":{"summary":"Get tracked AI search engines","value":{"config_type":"search_engines","account_id":101}},"locales":{"summary":"Get locales used by tracked topics","value":{"config_type":"locales","account_id":101}},"languages":{"summary":"Get languages in use for tracked topics","value":{"config_type":"languages","account_id":101}},"brands":{"summary":"Get tracked brands with owned and comparison web properties","value":{"config_type":"brands","account_id":101}},"personas":{"summary":"Get personas for account","value":{"config_type":"personas","account_id":101}},"intents":{"summary":"Get intents in use","value":{"config_type":"intents","account_id":101}},"sentiment_categories":{"summary":"Get sentiment categories in use","value":{"config_type":"sentiment_categories","account_id":101}}}}},"required":true},"responses":{"200":{"description":"Query completed successfully (returned when polling with queryExecutionId).\nThe response `schema` and `results` tuple structure vary by `config_type` — see Config Types above.\nThe default schema example below shows the `prompts` config_type response.\nNamed 200 response examples are also provided for each supported `config_type`.\n","content":{"application/json":{"schema":{"type":"object","example":{"results":[["best seo practices for 2025","unbranded","ACTIVE","2025-01-01","WEEKLY","ai seo tools","ChatGPT (Search)","US","English","Education","seo"]],"schema":[{"name":"prompt","type":"string"},{"name":"prompt_type","type":"string"},{"name":"prompt_status","type":"string"},{"name":"tracking_start_date","type":"date"},{"name":"tracking_frequency","type":"string","description":"Collection frequency. One of: DAILY, WEEKLY, MONTHLY."},{"name":"topic_name","type":"string"},{"name":"search_engine","type":"string"},{"name":"locode","type":"string"},{"name":"language","type":"string"},{"name":"intent","type":"string"},{"name":"persona","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444444","requestId":"req-123","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000},"properties":{"results":{"type":"array","description":"List of query results. Each item is a positional tuple row.\nAvailable only when `executionState` is `COMPLETED`.\nColumn order depends on `config_type` — use the `schema` field to interpret positions.\n","items":{"$ref":"#/components/schemas/AiSearchConfigRow"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}},"examples":{"topics":{"summary":"Topics response","value":{"results":[["ai seo tools","ACTIVE","ChatGPT (Search)","WEEKLY","US","12"]],"schema":[{"name":"topic_name","type":"string"},{"name":"topic_status","type":"string"},{"name":"search_engine","type":"string"},{"name":"tracking_frequency","type":"string","description":"Collection frequency. One of: DAILY, WEEKLY, MONTHLY."},{"name":"locode","type":"string"},{"name":"prompt_count","type":"integer"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-555555555551","requestId":"req-201","totalRowCount":1}},"prompts":{"summary":"Prompts response","value":{"results":[["best seo practices for 2025","unbranded","ACTIVE","2025-01-01","WEEKLY","ai seo tools","ChatGPT (Search)","US","English","Education","seo"]],"schema":[{"name":"prompt","type":"string"},{"name":"prompt_type","type":"string"},{"name":"prompt_status","type":"string"},{"name":"tracking_start_date","type":"date"},{"name":"tracking_frequency","type":"string","description":"Collection frequency. One of: DAILY, WEEKLY, MONTHLY."},{"name":"topic_name","type":"string"},{"name":"search_engine","type":"string"},{"name":"locode","type":"string"},{"name":"language","type":"string"},{"name":"intent","type":"string"},{"name":"persona","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444444","requestId":"req-123","nextPageId":"87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==","totalRowCount":1000}},"search_engines":{"summary":"Search engines response","value":{"results":[["ChatGPT (Search)"],["Perplexity"]],"schema":[{"name":"name","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-555555555552","requestId":"req-202","totalRowCount":2}},"locales":{"summary":"Locales response","value":{"results":[["US"],["GB"]],"schema":[{"name":"locode","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-555555555553","requestId":"req-203","totalRowCount":2}},"languages":{"summary":"Languages response","value":{"results":[["English"],["Spanish"]],"schema":[{"name":"name","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-555555555554","requestId":"req-204","totalRowCount":2}},"brands":{"summary":"Brands response (owned and comparison web properties)","value":{"results":[["Conductor","456","conductor.com","true"],["Searchlight","789","searchlight.com","false"]],"schema":[{"name":"brand_name","type":"string"},{"name":"web_property_id","type":"integer"},{"name":"web_property_name","type":"string"},{"name":"is_owned","type":"boolean","description":"True when the web property is account-owned; false when it is a comparison web property."}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-555555555555","requestId":"req-205","totalRowCount":2}},"personas":{"summary":"Personas response","value":{"results":[["seo","SEO practitioner persona"],["executive","Executive stakeholder persona"]],"schema":[{"name":"name","type":"string"},{"name":"description","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-555555555556","requestId":"req-206","totalRowCount":2}},"intents":{"summary":"Intents response","value":{"results":[["Education"],["Comparison"]],"schema":[{"name":"name","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-555555555557","requestId":"req-207","totalRowCount":2}},"sentiment_categories":{"summary":"Sentiment categories response","value":{"results":[["pricing"],["support"]],"schema":[{"name":"sentiment_category","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-555555555558","requestId":"req-208","totalRowCount":2}}}}}},"202":{"description":"Query accepted and is being processed asynchronously","content":{"application/json":{"schema":{"type":"object","example":{"results":[],"schema":[],"executionState":"IN_PROGRESS","executionId":"enga:b3d8a1c7-9f2e-4d6a-a5b1-8c4e2f7d9a03","requestId":"4e2c8f19-7a3d-4b5e-9c1f-6d8a2e4b7f30"},"properties":{"results":{"type":"array","description":"Empty array when `executionState` is `IN_PROGRESS`.\nAvailable once `executionState` becomes `COMPLETED`.\n","items":{"type":"object"}},"executionState":{"type":"string","description":"Current execution state of the query:\n- `IN_PROGRESS`: The query is still running. Poll again later.\n- `COMPLETED`: The query finished successfully. Results are available.\n- `FAILED`: The query failed. Check the error message if available.\n","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"executionId":{"type":"string","description":"Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination."},"requestId":{"type":"string","description":"Unique identifier for the HTTP request, useful for support and debugging."},"nextPageId":{"type":"string","description":"Token for retrieving the next page of results. Available as long as the executionId is valid (7 days).\nIf `null`, there are no more pages available.\n"},"totalRowCount":{"type":"integer","format":"int64","description":"Total number of rows across all pages (if available)."},"schema":{"type":"array","description":"Column metadata providing the name and type for each position in the results tuple.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","example":{"error":"INVALID_PARAMETERS","message":"config_type must be one of: topics, prompts, search_engines, locales, languages, brands, personas, intents, sentiment_categories"},"properties":{"error":{"type":"string","description":"Error code or identifier"},"message":{"type":"string","description":"Detailed error message"}}}}}},"401":{"description":"Unauthorized - API key missing or invalid"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"KeywordRankingsRequest":{"type":"object","description":"Request schema for submitting a new keyword rankings query.","properties":{"account_id":{"type":"integer","description":"Required account ID to filter results.","example":101,"minimum":1},"start_date":{"type":"string","format":"date","description":"Start date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Sunday.\nMaximum date range is 7 days.\n","example":"2025-01-01","x-valid-date-start":"collection_frequency","x-max-date-range-days":7,"x-start-date-1":true},"end_date":{"type":"string","format":"date","description":"End date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Saturday.\n","example":"2025-03-03","x-valid-date-end":"collection_frequency","x-end-date-1":true},"collection_frequency":{"type":"string","default":"WEEKLY","description":"Frequency of data collection.","enum":["DAILY","WEEKLY"],"example":"DAILY"},"min_rank":{"type":"integer","default":1,"description":"Minimum rank to include in results.","example":1,"maximum":101,"minimum":1},"max_rank":{"type":"integer","description":"(Optional) Maximum rank to include in results.","example":100,"minimum":1},"result_types":{"type":"array","description":"(Optional) list of types of search results to include (e.g., STANDARD_LINK).","example":["STANDARD_LINK"],"items":{"type":"string"}},"domains":{"type":"array","description":"(Optional) list of domains to filter SERP items by.","example":["conductor.com","seo.com"],"items":{"type":"string"}},"includeMsv":{"type":"boolean","default":false,"description":"(Optional) Whether to include MSV (Monthly Search Volume) data.","example":true},"keyword_group_ids":{"type":"array","description":"(Optional) list of keyword group IDs to filter results. If provided, this takes priority over `keyword_group_names`.","example":[1,204,13],"items":{"type":"integer","minimum":1}},"keyword_group_names":{"type":"array","description":"(Optional) list of keyword group names to filter results. Used only if `keyword_group_ids` is empty.","example":["Brand","Non-Brand","Other Category"],"items":{"type":"string"}},"web_property_ids":{"type":"array","description":"(Optional) list of web property IDs to filter results.","example":[122556,987654],"items":{"type":"integer","minimum":1}},"rank_source_ids":{"type":"array","description":"(Optional) list of rank source IDs to filter results.","example":[101,205,333],"items":{"type":"integer","minimum":1}},"devices":{"type":"array","description":"(Optional) list of device types to filter (case-insensitive).","example":["DESKTOP","SMARTPHONE"],"items":{"type":"string","enum":["DESKTOP","SMARTPHONE","TABLET"]}},"locodes":{"type":"array","description":"(Optional) list of locodes to filter (case-insensitive). Based on ISO names from a predefined dictionary.\nA locode can represent a country (\"US\"), city (\"US NYC\"), state (\"PL-02\"), or a specific location (e.g., an airport).\n","example":["US","CA","US NYC","US-TX"],"items":{"type":"string","maxLength":12,"minLength":2}},"countries":{"type":"array","description":"(Optional) list of search engine country codes to filter (case-insensitive).","example":["US","CA"],"items":{"type":"string","maxLength":2,"minLength":2}},"languages":{"type":"array","description":"(Optional) list of search engine language codes to filter (case-insensitive; e.g., en, zh-Hans).","example":["en","zh-Hans"],"items":{"type":"string","maxLength":7,"minLength":2}}},"required":["account_id","end_date","start_date"]},"KeywordSearchConfigRow":{"type":"array","description":"Positional tuple row. Column order depends on `config_type`:\n\n**`keywords`** (8 columns): web_property_id, keyword, status, keyword_groups, tracking_start_date, locale, kw_search_engine, device\n\n**`keyword_groups`** (2 columns): keyword_group_id, keyword_group_name\n\n**`search_engines`** (1 column): name\n\n**`devices`** (1 column): name\n\n**`locales`** (1 column): locode\n\nUse the `schema` field in the response to interpret column positions.\n","items":{"type":"string"}},"WebPropertiesConfigRow":{"type":"array","description":"Positional tuple row for web properties configuration results.\nValues are returned as strings in the following order:\n1) web_property_id, 2) web_property_name, 3) root_domains.\n","items":{"type":"string"},"maxItems":3,"minItems":3},"ComparisonWebPropertiesConfigRow":{"type":"array","description":"Positional tuple row for comparison web properties configuration results.\nValues are returned as strings in the following order:\n1) web_property_id, 2) web_property_name, 3) attribution_label, 4) root_domains, 5) compared_against.\n","items":{"type":"string"},"maxItems":5,"minItems":5},"AiSearchCitationsRequest":{"type":"object","description":"Request schema for submitting a new AI Search Citations query.","properties":{"account_id":{"type":"integer","description":"Required account ID to filter results.","example":101,"minimum":1},"start_date":{"type":"string","format":"date","description":"Start date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Sunday.\nIf `collection_frequency` is `MONTHLY`, this must be the first day of the month.\n","example":"2025-11-02","x-valid-date-start":"collection_frequency"},"end_date":{"type":"string","format":"date","description":"End date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Saturday.\nIf `collection_frequency` is `MONTHLY`, this must be the last day of the month.\n","example":"2025-11-29","x-valid-date-end":"collection_frequency"},"collection_frequency":{"type":"string","default":"WEEKLY","description":"Frequency of data collection.","enum":["DAILY","WEEKLY","MONTHLY"]},"web_property_ids":{"type":"array","description":"(Optional) list of web property IDs to filter results.","example":[122556,987654],"items":{"type":"integer","minimum":1}},"ai_search_engines":{"type":"array","description":"(Optional) list of AI engines to filter.","example":["chatgptsearch","perplexity"],"items":{"type":"string"}},"locodes":{"type":"array","description":"(Optional) list of locodes to filter (case-insensitive). Based on ISO names from a predefined dictionary.\nA locode can represent a country (\"US\"), city (\"US NYC\"), state (\"PL-02\"), or a specific location (e.g., an airport).\n","example":["US","CA","US NYC","US-TX"],"items":{"type":"string","maxLength":12,"minLength":2}},"languages":{"type":"array","description":"(Optional) list of search engine language codes to filter (case-insensitive; e.g., en_US, hant_TW).","example":["en_US","hant_TW"],"items":{"type":"string","maxLength":7,"minLength":2}},"topics":{"type":"array","description":"(Optional) list of topics to filter.","example":["marketing automation","website optimization"],"items":{"type":"string"}},"prompts":{"type":"array","description":"(Optional) list of prompts to filter.","example":["best crm","top crm"],"items":{"type":"string"}},"prompt_type":{"type":"string","description":"(Optional) indicates whether the prompt is branded or unbranded.","enum":["branded","unbranded"],"example":"branded"},"intents":{"type":"array","description":"(Optional) list of intents to filter. Options include: \nEducation, Brand/Service Navigation, Pricing, Support, Recommendations, Comparison, Purchase, Other.\n","example":["Education","Purchase"],"items":{"type":"string"}},"personas":{"type":"array","description":"(Optional) list of user-defined personas to filter (e.g., \"android user\", \"developers\").","example":["young adults","developers"],"items":{"type":"string"}},"root_domains":{"type":"array","description":"(Optional) list of root domains to filter.","example":["conductor.com","abc.com"],"items":{"type":"string"}},"domains":{"type":"array","description":"(Optional) list of domains to filter (e.g., blog.conductor.com).","example":["blog.conductor.com","about.conductor.com"],"items":{"type":"string"}},"citation_urls":{"type":"array","description":"(Optional) list of citation URLs to filter.","example":["https://www.conductor.com/blog/conductor-record-enterprise-momentum-ai-search/","https://www.conductor.com/academy/debunking-ai-prompt-volume/"],"items":{"type":"string"}},"citation_attributions":{"type":"array","description":"(Optional) list of citation ownership to filter (case-insensitive).","example":["You","Partner","SEO Competitor","Other"],"items":{"type":"string"}}},"required":["account_id","end_date","start_date"]},"AiSearchConfigRow":{"type":"array","description":"Positional tuple row. Column order depends on `config_type`:\n\n**`topics`** (6 columns): topic_name, topic_status, search_engine, tracking_frequency (DAILY, WEEKLY, or MONTHLY), locode, prompt_count\n\n**`prompts`** (11 columns): prompt, prompt_type, prompt_status, tracking_start_date, tracking_frequency (DAILY, WEEKLY, or MONTHLY), topic_name, search_engine, locode, language, intent, persona\n\n**`search_engines`** (1 column): name\n\n**`locales`** (1 column): locode\n\n**`languages`** (1 column): name\n\n**`brands`** (4 columns): brand_name, web_property_id, web_property_name, is_owned (`true` for owned, `false` for comparison)\n\n**`personas`** (2 columns): name, description\n\n**`intents`** (1 column): name\n\n**`sentiment_categories`** (1 column): sentiment_category\n\nUse the `schema` field in the response to interpret column positions.\n","items":{"type":"string"}},"AiSearchConfigRequest":{"type":"object","description":"Request schema for submitting a new AI search configuration query.\nThe `config_type` determines which data is returned and which optional filters apply.\n","properties":{"config_type":{"type":"string","description":"Type of AI search configuration data to return:\n- `topics`: Tracked topics with status, search engine, frequency, locale, and prompt count.\n- `prompts`: Individual prompts with type, status, topic, search engine, locale, language, intent, and persona.\n- `search_engines`: Distinct AI search engines used by tracked topics.\n- `locales`: Distinct locales used by tracked topics.\n- `languages`: Distinct languages used by tracked topics.\n- `brands`: Tracked brands with associated owned and comparison web properties.\n- `personas`: Personas defined for the account.\n- `intents`: Distinct intents used by tracked prompts.\n- `sentiment_categories`: Distinct sentiment categories observed in AI search results.\n","enum":["topics","prompts","search_engines","locales","languages","brands","personas","intents","sentiment_categories"],"example":"prompts"},"account_id":{"type":"integer","description":"Required account ID to filter results.","example":101,"minimum":1},"topic_status":{"type":"string","default":"ACTIVE","description":"(Optional, `topics` and `prompts` only) Comma-separated topic statuses to include.\nAccepted values: `ACTIVE`, `INACTIVE`. An empty string disables the filter. Default is `ACTIVE`.\n","example":"ACTIVE"},"prompt_status":{"type":"string","default":"ACTIVE","description":"(Optional, `topics` and `prompts` only) Comma-separated prompt statuses to include.\nAccepted values: `ACTIVE`, `INACTIVE`. An empty string disables the filter. Default is `ACTIVE`.\n","example":"ACTIVE"},"topics":{"type":"string","description":"(Optional, `prompts` only) Comma-separated list of topic names to filter prompts by.","example":"ai search,seo tools"},"limit":{"type":"integer","default":100,"description":"Maximum number of rows to return for the submitted query.","example":100,"minimum":1}},"required":["account_id","config_type"]},"AiSearchBrandsRow":{"type":"array","description":"Positional tuple row for AI Search Brand results. Column order matches the `schema` metadata. All values are returned as strings.\n","items":{"type":"string"},"minItems":22},"KeywordSearchConfigRequest":{"type":"object","description":"Request schema for submitting a new keyword configuration query.\nThe `config_type` determines which data is returned and which optional filters apply.\n","properties":{"config_type":{"type":"string","description":"Type of keyword configuration data to return:\n- `keywords`: All tracked keywords with status, groups, locale, search engine, and device.\n- `keyword_groups`: Keyword groups defined for the account.\n- `search_engines`: Distinct search engines used by tracked keywords.\n- `devices`: Distinct devices used by tracked keywords.\n- `locales`: Distinct locales used by tracked keywords.\n","enum":["keywords","keyword_groups","search_engines","devices","locales"],"example":"keywords"},"account_id":{"type":"integer","description":"Required account ID to filter results.","example":101,"minimum":1},"web_property_id":{"type":"integer","description":"(Optional, `keywords` only) Filter results to a specific web property.","example":456},"keyword_group_id":{"type":"string","description":"(Optional, `keywords` only) Filter results to keywords in a specific keyword group.","example":"995895"},"keyword_status":{"type":"string","default":"ACTIVE","description":"(Optional, `keywords` only) Comma-separated keyword statuses to include.\nAccepted values: `ACTIVE`, `INACTIVE`. An empty string disables the filter. Default is `ACTIVE`.\n","example":"ACTIVE"},"limit":{"type":"integer","default":100,"description":"Maximum number of rows to return for the submitted query.","example":100,"minimum":1}},"required":["account_id","config_type"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"},"details":{"type":"object","description":"Additional error details"}}},"WebPropertiesConfigRequest":{"type":"object","description":"Request schema for submitting a new web properties configuration query.","properties":{"account_id":{"type":"integer","description":"Required account ID to filter web properties.","example":101,"minimum":1},"limit":{"type":"integer","default":100,"description":"Maximum number of rows to return for the submitted query.","example":100,"minimum":1}},"required":["account_id"]},"AiSearchResponseRequest":{"type":"object","properties":{"time_period_start":{"type":"string","format":"date","description":"Start date of the time period; if collection_frequency is WEEKLY, this field must be Sunday; if MONTHLY, must be the first day of the month","example":"2025-11-02","x-valid-date-start":"collection_frequency"},"time_period_end":{"type":"string","format":"date","description":"End date of the time period; if collection_frequency is WEEKLY, this field must be Saturday; if MONTHLY, must be the last day of the month","example":"2025-11-08","x-valid-date-end":"collection_frequency"},"collection_frequency":{"type":"string","description":"Data collection frequency","enum":["DAILY","WEEKLY","MONTHLY"]},"limit":{"type":"integer","default":1000,"description":"Maximum number of results to return","example":100,"maximum":1000,"minimum":0},"account_id":{"type":"integer","description":"Required account ID to filter results","example":101,"minimum":1},"web_property_ids":{"type":"array","description":"(Optional) comma-separated list of web property IDs to filter results. If not provided, results are not filtered by web property","example":[122556,987654],"items":{"type":"integer","minimum":1}},"ai_search_engines":{"type":"array","description":"(Optional) comma-separated list of AI engines to filter","example":["chatgptsearch","perplexity"],"items":{"type":"string"}},"locodes":{"type":"array","description":"(Optional) comma-separated list of locodes to filter (case-insensitive; values will be uppercased). Supports locales like country codes \"DE\" or city locodes \"US NYC\" or state codes \"PL-02\"","example":["US","CA","US NYC","US-TX"],"items":{"type":"string","maxLength":12,"minLength":2}},"languages":{"type":"array","description":"(Optional) comma-separated list of search engine language codes to filter (case-insensitive; values will be uppercased).","example":["en_US","hant_TW"],"items":{"type":"string","maxLength":7,"minLength":2}},"topics":{"type":"array","description":"(Optional) comma-separated list of topics to filter","example":["marketing automation","website optimization"],"items":{"type":"string"}},"prompts":{"type":"array","description":"(Optional) comma-separated list of prompts to filter","example":["best marketing automation tools","website optimization tools"],"items":{"type":"string"}},"intents":{"type":"array","description":"(Optional) comma-separated list of intents to filter","example":["Education","Purchase"],"items":{"type":"string"}},"personas":{"type":"array","description":"(Optional) comma-separated list of personas to filter","example":["young adults","developers"],"items":{"type":"string"}}},"required":["account_id","collection_frequency","time_period_end","time_period_start"]},"HighestRankingUrlPerKeywordRow":{"type":"array","description":"Positional tuple row for highest ranking URL per keyword results. Column order matches the `schema` metadata. All values are returned as strings.\n","items":{"type":"string"},"maxItems":31,"minItems":26},"AiSearchSentimentsRequest":{"type":"object","description":"Request schema for submitting a new AI Search Sentiments query.","properties":{"account_id":{"type":"integer","description":"Required account ID to filter results.","example":101,"minimum":1},"start_date":{"type":"string","format":"date","description":"Start date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Sunday.\nIf `collection_frequency` is `MONTHLY`, this must be the first day of the month.\n","example":"2024-03-01","x-valid-date-start":"collection_frequency"},"end_date":{"type":"string","format":"date","description":"End date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Saturday.\nIf `collection_frequency` is `MONTHLY`, this must be the last day of the month.\n","example":"2024-03-15","x-valid-date-end":"collection_frequency"},"collection_frequency":{"type":"string","default":"WEEKLY","description":"Frequency of data collection.","enum":["DAILY","WEEKLY","MONTHLY"]},"web_property_ids":{"type":"array","description":"(Optional) list of web property IDs to filter results.","example":[122556,987654],"items":{"type":"integer","minimum":1}},"ai_search_engines":{"type":"array","description":"(Optional) list of AI engines to filter.","example":["chatgptsearch"],"items":{"type":"string"}},"locodes":{"type":"array","description":"(Optional) list of locodes to filter (case-insensitive). Based on ISO names from a predefined dictionary.\nA locode can represent a country (\"US\"), city (\"US NYC\"), state (\"PL-02\"), or a specific location (e.g., an airport).\n","example":["US","CA","US NYC","US-TX"],"items":{"type":"string","maxLength":12,"minLength":2}},"languages":{"type":"array","description":"(Optional) list of search engine language codes to filter (case-insensitive; e.g., en_US, hant_TW).","example":["en_US","hant_TW"],"items":{"type":"string","maxLength":7,"minLength":2}},"topics":{"type":"array","description":"(Optional) list of topics to filter.","example":["marketing automation","website optimization"],"items":{"type":"string"}},"prompts":{"type":"array","description":"(Optional) list of prompts to filter.","example":["best crm","top crm"],"items":{"type":"string"}},"prompt_type":{"type":"string","description":"(Optional) indicates whether the prompt is branded or unbranded.","enum":["branded","unbranded"],"example":"branded"},"intents":{"type":"array","description":"(Optional) list of intents to filter. Options include: \nEducation, Brand/Service Navigation, Pricing, Support, Recommendations, Comparison, Purchase, Other.\n","example":["Education","Purchase"],"items":{"type":"string"}},"personas":{"type":"array","description":"(Optional) list of user-defined personas to filter (e.g., \"android user\", \"developers\").","example":["young adults","developers"],"items":{"type":"string"}},"sentiment_brands":{"type":"array","description":"(Optional) list of sentiment brands to filter (case-insensitive).","example":["Conductor","Conductor AI"],"items":{"type":"string"}},"sentiment_values":{"type":"array","description":"(Optional) list of sentiment values to filter.","example":["positive"],"items":{"type":"string","enum":["positive","neutral","negative"]}},"sentiment_categories":{"type":"array","description":"(Optional) list of sentiment categories to filter.","example":["pricing"],"items":{"type":"string"}},"sentiment_source_domains":{"type":"array","description":"(Optional) list of sentiment source domains to filter.","example":["example.com"],"items":{"type":"string"}}},"required":["account_id","end_date","start_date"]},"KeywordRankingRow":{"type":"array","description":"Positional tuple row for keyword rankings results. Column order matches the `schema` metadata. All values are returned as strings.\n","items":{"type":"string"},"maxItems":31,"minItems":26},"HighestRankingUrlPerKeywordRequest":{"type":"object","description":"Request schema for submitting a new highest ranking URL per keyword query.","properties":{"account_id":{"type":"integer","description":"Required account ID to filter results.","example":101,"minimum":1},"start_date":{"type":"string","format":"date","description":"Start date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Sunday.\nMaximum date range is 92 days.\n","example":"2025-01-01","x-valid-date-start":"collection_frequency","x-max-date-range-days":92,"x-start-date-1":true},"end_date":{"type":"string","format":"date","description":"End date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Saturday.\n","example":"2025-03-03","x-valid-date-end":"collection_frequency","x-end-date-1":true},"collection_frequency":{"type":"string","default":"WEEKLY","description":"Frequency of data collection.","enum":["DAILY","WEEKLY"],"example":"DAILY"},"result_types":{"type":"array","description":"(Optional) list of types of search results to include (e.g., STANDARD_LINK).","example":["STANDARD_LINK"],"items":{"type":"string"}},"domains":{"type":"array","description":"(Optional) list of domains to filter SERP items by.","example":["conductor.com","seo.com"],"items":{"type":"string"}},"includeMsv":{"type":"boolean","default":false,"description":"(Optional) Whether to include MSV (Monthly Search Volume) data.","example":true},"keyword_group_ids":{"type":"array","description":"(Optional) list of keyword group IDs to filter results. If provided, this takes priority over `keyword_group_names`.","example":[1,204,13],"items":{"type":"integer","minimum":1}},"keyword_group_names":{"type":"array","description":"(Optional) list of keyword group names to filter results. Used only if `keyword_group_ids` is empty.","example":["Brand","Non-Brand","Category"],"items":{"type":"string"}},"web_property_ids":{"type":"array","description":"(Optional) list of web property IDs to filter results.","example":[122556,987654],"items":{"type":"integer","minimum":1}},"rank_source_ids":{"type":"array","description":"(Optional) list of rank source IDs to filter results.","example":[101,205,333],"items":{"type":"integer","minimum":1}},"devices":{"type":"array","description":"(Optional) list of device types to filter (case-insensitive).","example":["DESKTOP","SMARTPHONE"],"items":{"type":"string","enum":["DESKTOP","SMARTPHONE","TABLET"]}},"locodes":{"type":"array","description":"(Optional) list of locodes to filter (case-insensitive). Based on ISO names from a predefined dictionary.\nA locode can represent a country (\"US\"), city (\"US NYC\"), state (\"PL-02\"), or a specific location (e.g., an airport).\n","example":["US","CA","US NYC","US-TX"],"items":{"type":"string","maxLength":12,"minLength":2}},"countries":{"type":"array","description":"(Optional) list of search engine country codes to filter (case-insensitive).","example":["US","CA"],"items":{"type":"string","maxLength":2,"minLength":2}},"languages":{"type":"array","description":"(Optional) list of search engine language codes to filter (case-insensitive; e.g., en, zh-Hans).","example":["en","zh-Hans"],"items":{"type":"string","maxLength":7,"minLength":2}}},"required":["account_id","end_date","start_date"]},"AiSearchCitationsRow":{"type":"array","description":"Positional tuple row for AI Search Citation results. Column order matches the `schema` metadata. All values are returned as strings.\n","items":{"type":"string"},"minItems":24},"AiSearchResponseRow":{"type":"array","description":"Positional tuple row for AI Search Response results. Column order matches the `schema` metadata. All values are returned as strings.\n","items":{"type":"string"},"minItems":19},"ComparisonWebPropertiesConfigRequest":{"type":"object","description":"Request schema for submitting a new comparison web properties configuration query.","properties":{"account_id":{"type":"integer","description":"Required account ID to filter comparison web properties.","example":101,"minimum":1},"limit":{"type":"integer","default":100,"description":"Maximum number of rows to return for the submitted query.","example":100,"minimum":1}},"required":["account_id"]},"AiSearchResponseResponse":{"type":"object","properties":{"organization_name":{"type":"string","description":"The name of the parent organization","example":"Example Organization"},"organization_id":{"type":"string","description":"The id of the parent organization","example":"DF3DAF2955754FDDB180CF505AE4761E"},"account_name":{"type":"string","description":"The name of the account","example":"Example Account"},"account_id":{"type":"integer","description":"The id of the account","example":123},"web_property_name":{"type":"string","description":"The name of the website or property","example":"conductor.com"},"web_property_id":{"type":"integer","description":"The id of the website or property","example":456},"collection_frequency":{"type":"string","description":"Data collection frequency","enum":["DAILY","WEEKLY","MONTHLY"]},"time_period_start":{"type":"string","format":"date","description":"Start date of the time period","example":"2025-11-02"},"time_period_end":{"type":"string","format":"date","description":"End date of the time period","example":"2025-11-08"},"locode":{"type":"string","description":"Location code where the search was made","example":"US"},"language":{"type":"string","description":"Language code of the topic and prompt","example":"en_US"},"ai_search_engine_id":{"type":"string","description":"AI Search Engine ID","example":"engine-123"},"ai_search_engine":{"type":"string","description":"AI Search Engine Name","example":"chatgptsearch"},"topic":{"type":"string","description":"The topic associated with the prompt","example":"marketing automation"},"prompt":{"type":"string","description":"The specific prompt text","example":"best marketing automation tools"},"intent":{"type":"string","description":"The intent category of the prompt","example":"commercial"},"persona":{"type":"string","description":"The persona associated with the prompt","example":"Marketing Manager"},"ai_response":{"type":"string","description":"The AI-generated response content","example":"Here are some of the best marketing automation tools available..."},"collection_date":{"type":"string","format":"date","description":"The specific date on which the AI response data was collected","example":"2024-03-15"}}},"AiSearchSentimentsRow":{"type":"array","description":"Positional tuple row for AI search sentiments results. Column order matches the `schema` metadata. All values are returned as strings.\n","items":{"type":"string"},"maxItems":26,"minItems":26},"AiSearchBrandsRequest":{"type":"object","description":"Request schema for submitting a new AI Search Brand data query.","properties":{"account_id":{"type":"integer","description":"Required account ID to filter results.","example":101,"minimum":1},"start_date":{"type":"string","format":"date","description":"Start date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Sunday.\nIf `collection_frequency` is `MONTHLY`, this must be the first day of the month.\n","example":"2025-11-02","x-valid-date-start":"collection_frequency"},"end_date":{"type":"string","format":"date","description":"End date of the time period (yyyy-MM-dd).\nIf `collection_frequency` is `WEEKLY` or not set, this must be a Saturday.\nIf `collection_frequency` is `MONTHLY`, this must be the last day of the month.\n","example":"2025-11-29","x-valid-date-end":"collection_frequency"},"collection_frequency":{"type":"string","default":"WEEKLY","description":"Frequency of data collection.","enum":["DAILY","WEEKLY","MONTHLY"]},"web_property_ids":{"type":"array","description":"(Optional) list of web property IDs to filter results.","example":[122556,987654],"items":{"type":"integer","minimum":1}},"ai_search_engines":{"type":"array","description":"(Optional) list of AI engines to filter.","example":["chatgptsearch","perplexity"],"items":{"type":"string"}},"locodes":{"type":"array","description":"(Optional) list of locodes to filter (case-insensitive). Based on ISO names from a predefined dictionary.\nA locode can represent a country (\"US\"), city (\"US NYC\"), state (\"PL-02\"), or a specific location (e.g., an airport).\n","example":["US","CA","US NYC","US-TX"],"items":{"type":"string","maxLength":12,"minLength":2}},"languages":{"type":"array","description":"(Optional) list of search engine language codes to filter (case-insensitive; e.g., en_US, hant_TW).","example":["en_US","hant_TW"],"items":{"type":"string","maxLength":7,"minLength":2}},"topics":{"type":"array","description":"(Optional) list of topics to filter.","example":["marketing automation","website optimization"],"items":{"type":"string"}},"prompts":{"type":"array","description":"(Optional) list of prompts to filter.","example":["best crm","top crm"],"items":{"type":"string"}},"prompt_type":{"type":"string","description":"(Optional) indicates whether the prompt is branded or unbranded.","enum":["branded","unbranded"],"example":"branded"},"intents":{"type":"array","description":"(Optional) list of intents to filter. Options include: \nEducation, Brand/Service Navigation, Pricing, Support, Recommendations, Comparison, Purchase, Other.\n","example":["Education","Purchase"],"items":{"type":"string"}},"personas":{"type":"array","description":"(Optional) list of user-defined personas to filter (e.g., \"android user\", \"developers\").","example":["young adults","developers"],"items":{"type":"string"}},"brand_or_product_names":{"type":"array","description":"(Optional) list of brands and products to filter (case-insensitive).","example":["Conductor","Conductor AI"],"items":{"type":"string"}},"brand_or_product_attributions":{"type":"array","description":"(Optional) list of brand or product ownership to filter (case-insensitive).","example":["You","Partner","SEO Competitor","Other"],"items":{"type":"string"}}},"required":["account_id","end_date","start_date"]}},"securitySchemes":{"ApiKeyQuery":{"type":"apiKey","description":"API Key as a query parameter","name":"apiKey","in":"query"},"SigQuery":{"type":"apiKey","description":"Request signature computed using API key and secret. Valid for 5 minutes after creation.","name":"sig","in":"query"}}}}