{"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, made through the API Gateway.\n\n**Recommended: Conductor API token**\n\nSend your Conductor API token in the `Authorization` header:\n\n```\nAuthorization: Bearer cond_<your-api-token>\n```\n\nGenerate a token from Integrations > API > Create API Token in the Conductor app.\n\n<details>\n<summary><b>Legacy: API key and signature (still supported)</b></summary>\n\nConductor still supports existing connections using this legacy method. We recommend new connections use the API token method described above.\n\nAll endpoints accept 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":[{"ApiToken":[]},{"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"}]},"examples":{"keyword_rankings":{"summary":"Get keyword rankings for account","value":{"account_id":101,"start_date":"2025-11-02","end_date":"2025-11-08","collection_frequency":"WEEKLY","min_rank":1,"max_rank":100,"result_types":["STANDARD_LINK"],"domains":["conductor.com","seo.com"],"includeMsv":true,"keyword_group_ids":[1,204,13],"keyword_group_names":["Brand","Non-Brand","Other Category"],"web_property_ids":[122556,987654],"rank_source_ids":[101,205,333],"devices":["DESKTOP","SMARTPHONE"],"locodes":["US","CA","US NYC","US-TX"],"countries":["US","CA"],"languages":["en","zh-Hans"]}}}}},"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"}]},"examples":{"highest_ranking_url_per_keyword":{"summary":"Get highest ranking URL per keyword for account","value":{"account_id":101,"start_date":"2025-11-02","end_date":"2025-11-08","collection_frequency":"WEEKLY","result_types":["STANDARD_LINK"],"domains":["conductor.com","seo.com"],"includeMsv":true,"keyword_group_ids":[1,204,13],"keyword_group_names":["Brand","Non-Brand","Category"],"web_property_ids":[122556,987654],"rank_source_ids":[101,205,333],"devices":["DESKTOP","SMARTPHONE"],"locodes":["US","CA","US NYC","US-TX"],"countries":["US","CA"],"languages":["en","zh-Hans"]}}}}},"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"}]},"examples":{"ai_search_brands":{"summary":"Get AI search brand data for account","value":{"account_id":101,"start_date":"2025-11-02","end_date":"2025-11-08","collection_frequency":"WEEKLY","web_property_ids":[122556,987654],"ai_search_engines":["chatgptsearch","perplexity"],"locodes":["US","CA","US NYC","US-TX"],"languages":["en_US","hant_TW"],"topics":["marketing automation","website optimization"],"prompts":["best crm","top crm"],"prompt_type":"branded","intents":["Education","Purchase"],"personas":["young adults","developers"],"brand_or_product_names":["Conductor","Conductor AI"],"brand_or_product_attributions":["You","Partner","SEO Competitor","Other"],"prompts_groups":["Comparison Prompts"],"prompts_groups_match":"any"}}}}},"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","Brand Prompts, Competitor Prompts"]],"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"},{"name":"prompt_group_names","type":"string"}],"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"}]},"examples":{"ai_search_citations":{"summary":"Get AI search citation data for account","value":{"account_id":101,"start_date":"2025-11-02","end_date":"2025-11-08","collection_frequency":"WEEKLY","web_property_ids":[122556,987654],"ai_search_engines":["chatgptsearch","perplexity"],"locodes":["US","CA","US NYC","US-TX"],"languages":["en_US","hant_TW"],"topics":["marketing automation","website optimization"],"prompts":["best crm","top crm"],"prompt_type":"branded","intents":["Education","Purchase"],"personas":["young adults","developers"],"root_domains":["conductor.com","abc.com"],"domains":["blog.conductor.com","about.conductor.com"],"citation_urls":["https://www.conductor.com/blog/conductor-record-enterprise-momentum-ai-search/","https://www.conductor.com/academy/debunking-ai-prompt-volume/"],"citation_attributions":["You","Partner","SEO Competitor","Other"],"prompts_groups":["Comparison Prompts"],"prompts_groups_match":"any"}}}}},"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","Brand Prompts, Competitor Prompts"]],"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"},{"name":"prompt_group_names","type":"string"}],"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_fan_out":{"post":{"tags":["AI / Foundational"],"summary":"Get AI Search Fan Out Data (Async)","description":"Execute a query to get fan out (sub-search) 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":"queryAiSearchFanOutAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/AiSearchFanOutRequest"}],"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"}]},"examples":{"ai_search_fan_out":{"summary":"Get AI search fan out data for account","value":{"account_id":101,"start_date":"2025-11-02","end_date":"2025-11-08","collection_frequency":"WEEKLY","web_property_ids":[122556,987654],"ai_search_engines":["chatgptsearch","perplexity"],"locodes":["US","CA","US NYC","US-TX"],"languages":["en_US","hant_TW"],"topics":["marketing automation","website optimization"],"prompts":["best crm","top crm"],"prompt_type":"branded","intents":["Education","Purchase"],"personas":["young adults","developers"],"prompts_groups":["Comparison Prompts"],"prompts_groups_match":"any"}}}}},"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","marketing automation","best crm tools","unbranded","Purchase","developers","best crm tools for small business 2026","1","8","true","true","Comparison Prompts"]],"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":"fan_out_query","type":"string"},{"name":"fan_out_query_position","type":"integer"},{"name":"amount_of_searches","type":"integer"},{"name":"web_search","type":"boolean"},{"name":"ai_response_received","type":"boolean"},{"name":"prompt_group_names","type":"string"}],"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/AiSearchFanOutRow"}},"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_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"}]},"examples":{"ai_search_sentiments":{"summary":"Get AI search sentiment data for account","value":{"account_id":101,"start_date":"2025-11-02","end_date":"2025-11-08","collection_frequency":"WEEKLY","web_property_ids":[122556,987654],"ai_search_engines":["chatgptsearch","perplexity"],"locodes":["US","CA","US NYC","US-TX"],"languages":["en_US","hant_TW"],"topics":["marketing automation","website optimization"],"prompts":["best crm","top crm"],"prompt_type":"branded","intents":["Education","Purchase"],"personas":["young adults","developers"],"sentiment_brands":["Conductor","Conductor AI"],"sentiment_values":["positive"],"sentiment_categories":["price"],"sentiment_source_domains":["example.com"],"prompts_groups":["Comparison Prompts"],"prompts_groups_match":"any"}}}}},"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","Brand Prompts, Competitor Prompts"]],"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"},{"name":"prompt_group_names","type":"string"}],"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"}]},"examples":{"ai_search_response":{"summary":"Get AI search response data for account","value":{"time_period_start":"2025-11-02","time_period_end":"2025-11-08","collection_frequency":"WEEKLY","account_id":101,"limit":100,"web_property_ids":[122556,987654],"ai_search_engines":["chatgptsearch","perplexity"],"locodes":["US","CA","US NYC","US-TX"],"languages":["en_US","hant_TW"],"topics":["marketing automation","website optimization"],"prompts":["best marketing automation tools","website optimization tools"],"intents":["Education","Purchase"],"personas":["young adults","developers"],"prompts_groups":["Comparison Prompts"],"prompts_groups_match":"any"}}}}},"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","Brand Prompts, Competitor Prompts"]],"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"},{"name":"prompt_group_names","type":"string"}],"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/accounts_config":{"post":{"tags":["Configuration"],"summary":"Query Accounts Configuration (Async)","description":"\nExecute an asynchronous query against the accounts config dataset to get\nthe organizations and accounts accessible via the API key. This endpoint follows\nthe 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":"queryAccountsConfigAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/AccountsConfigRequest"}],"description":"Submit a new query for accounts. Results are scoped to the accounts accessible via the API key. 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":{"accounts":{"summary":"Get accounts accessible via the API key","value":{}}}}},"required":false},"responses":{"200":{"description":"Query completed successfully (returned when polling with queryExecutionId)","content":{"application/json":{"schema":{"type":"object","example":{"results":[["XYZXYZXYZXYXYZXYZXYZXYXYZXYZ1234","Example Organization","101","Example Account"]],"schema":[{"name":"organization_id","type":"string"},{"name":"organization_name","type":"string"},{"name":"account_id","type":"string"},{"name":"account_name","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-444444444444","requestId":"req-123","totalRowCount":1},"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/AccountsConfigRow"}},"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":"Unknown parameter(s) [foo]"},"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/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- **`prompt_groups`**: Account-defined groupings of tracked prompts, with each group's parent (if nested).\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\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}},"prompt_groups":{"summary":"Get prompt groups for account","value":{"config_type":"prompt_groups","account_id":101}},"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}}}}},"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}},"prompt_groups":{"summary":"Prompt groups response","value":{"results":[["3f2a9c14-8b21-4e7d-9a10-c5e2f8d41b09","Brand Awareness","Prompts where we track our own brand",null],["7c1e6b3a-4f9d-4a2c-8e5f-1d9a3b7c2e04","Competitor Watch",null,"Brand Awareness"]],"schema":[{"name":"prompt_group_id","type":"string"},{"name":"prompt_group_name","type":"string"},{"name":"description","type":"string"},{"name":"parent_group_name","type":"string"}],"executionState":"COMPLETED","executionId":"enga:abc12345-1111-2222-3333-555555555559","requestId":"req-209","totalRowCount":2}},"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}}}}}},"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, prompt_groups, search_engines, locales, languages, brands, personas, intents"},"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/page_groups_config":{"post":{"tags":["Configuration"],"summary":"Query Page Groups Configuration (Async)","description":"\nExecute an asynchronous query against the page groups config dataset to get\nthe page groups defined on owned web properties. This endpoint follows the asynchronous query flow.\n\nPage group names are only unique within a web property, so each row identifies both the page group\nand the web property it belongs to.\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":"queryPageGroupsConfigAsync","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/PageGroupsConfigRequest"}],"description":"Submit a new query for page groups. 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":{"page_groups":{"summary":"Get page groups for account","value":{"account_id":101}},"page_groups_for_web_properties":{"summary":"Get page groups for specific web properties","value":{"account_id":101,"web_property_ids":[122556,987654]}}}}},"required":true},"responses":{"200":{"description":"Query completed successfully (returned when polling with queryExecutionId)","content":{"application/json":{"schema":{"type":"object","example":{"results":[["8821","Blog","456","conductor.com"]],"schema":[{"name":"page_group_id","type":"string"},{"name":"page_group_name","type":"string"},{"name":"web_property_id","type":"string"},{"name":"web_property_name","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/PageGroupsConfigRow"}},"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"}}}}},"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. See [Accounts](/api/config-api/endpoints/accounts_config).","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`. See [Keyword Search](/api/config-api/endpoints/keyword_search_config).","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. See [Keyword Search](/api/config-api/endpoints/keyword_search_config).","example":["Brand","Non-Brand","Other Category"],"items":{"type":"string"}},"web_property_ids":{"type":"array","description":"(Optional) list of web property IDs to filter results. See [Web Properties](/api/config-api/endpoints/web_properties_config).","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). See [Keyword Search](/api/config-api/endpoints/keyword_search_config).","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).\nSee [Keyword Search](/api/config-api/endpoints/keyword_search_config).\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"]},"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},"PageGroupsConfigRow":{"type":"array","description":"Positional tuple row for page groups configuration results.\nValues are returned as strings in the following order:\n1) page_group_id, 2) page_group_name, 3) web_property_id, 4) web_property_name.\n","items":{"type":"string"},"maxItems":4,"minItems":4},"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},"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":23},"PageGroupsConfigRequest":{"type":"object","description":"Request schema for submitting a new page groups configuration query.","properties":{"account_id":{"type":"integer","description":"Required account ID to filter page groups.","example":101,"minimum":1},"web_property_ids":{"type":"array","description":"(Optional) list of web property IDs to filter page groups. See [Web Properties](/api/config-api/endpoints/web_properties_config).","example":[122556,987654],"items":{"type":"integer","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"]},"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. See [Accounts](/api/config-api/endpoints/accounts_config).","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. See [Web Properties](/api/config-api/endpoints/web_properties_config).","example":[122556,987654],"items":{"type":"integer","minimum":1}},"ai_search_engines":{"type":"array","description":"(Optional) comma-separated list of AI engines to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","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\". See [AI Search](/api/config-api/endpoints/ai_search_config).","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). See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["en_US","hant_TW"],"items":{"type":"string","maxLength":7,"minLength":2}},"topics":{"type":"array","description":"(Optional) comma-separated list of topics to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["marketing automation","website optimization"],"items":{"type":"string"}},"prompts":{"type":"array","description":"(Optional) comma-separated list of prompts to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["best marketing automation tools","website optimization tools"],"items":{"type":"string"}},"intents":{"type":"array","description":"(Optional) comma-separated list of intents to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["Education","Purchase"],"items":{"type":"string"}},"personas":{"type":"array","description":"(Optional) comma-separated list of personas to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["young adults","developers"],"items":{"type":"string"}},"prompts_groups":{"type":"array","description":"(Optional) list of prompt group names to filter (case-insensitive). See\n[AI Search](/api/config-api/endpoints/ai_search_config) with config_type=prompt_groups\nto discover group names.\n","example":["Comparison Prompts"],"items":{"type":"string"}},"prompts_groups_match":{"type":"string","default":"any","description":"(Optional) how `prompts_groups` combines multiple group names: `any` (default) matches\nat least one; `all` matches every listed group.\n","enum":["any","all"],"example":"any"}},"required":["account_id","collection_frequency","time_period_end","time_period_start"]},"AiSearchFanOutRequest":{"type":"object","description":"Request schema for submitting a new AI Search Fan Out data query.","properties":{"account_id":{"type":"integer","description":"Required account ID to filter results. See [Accounts](/api/config-api/endpoints/accounts_config).","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"]},"limit":{"type":"integer","default":1000,"description":"Maximum number of results to return. A value outside the 1 to 1,000 range is clamped into it rather than rejected.","example":100,"maximum":1000,"minimum":1},"web_property_ids":{"type":"array","description":"(Optional) list of web property IDs to filter results. See [Web Properties](/api/config-api/endpoints/web_properties_config).","example":[122556,987654],"items":{"type":"integer","minimum":1}},"ai_search_engines":{"type":"array","description":"(Optional) list of AI engines to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","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).\nSee [AI Search](/api/config-api/endpoints/ai_search_config).\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). See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["en_US","hant_TW"],"items":{"type":"string","maxLength":7,"minLength":2}},"topics":{"type":"array","description":"(Optional) list of topics to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["marketing automation","website optimization"],"items":{"type":"string"}},"prompts":{"type":"array","description":"(Optional) list of prompts to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","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.\nSee [AI Search](/api/config-api/endpoints/ai_search_config).\n","example":["Education","Purchase"],"items":{"type":"string"}},"personas":{"type":"array","description":"(Optional) list of user-defined personas to filter (e.g., \"android user\", \"developers\"). See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["young adults","developers"],"items":{"type":"string"}},"prompts_groups":{"type":"array","description":"(Optional) list of prompt group names to filter (case-insensitive). See\n[AI Search](/api/config-api/endpoints/ai_search_config) with config_type=prompt_groups\nto discover group names.\n","example":["Comparison Prompts"],"items":{"type":"string"}},"prompts_groups_match":{"type":"string","default":"any","description":"(Optional) how `prompts_groups` combines multiple group names: `any` (default) matches\nat least one; `all` matches every listed group.\n","enum":["any","all"],"example":"any"}},"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. See [Accounts](/api/config-api/endpoints/accounts_config).","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`. See [Keyword Search](/api/config-api/endpoints/keyword_search_config).","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. See [Keyword Search](/api/config-api/endpoints/keyword_search_config).","example":["Brand","Non-Brand","Category"],"items":{"type":"string"}},"web_property_ids":{"type":"array","description":"(Optional) list of web property IDs to filter results. See [Web Properties](/api/config-api/endpoints/web_properties_config).","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). See [Keyword Search](/api/config-api/endpoints/keyword_search_config).","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).\nSee [Keyword Search](/api/config-api/endpoints/keyword_search_config).\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":25},"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":20},"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":27,"minItems":27},"AiSearchFanOutRow":{"type":"array","description":"Positional tuple row for AI Search Fan Out results. Column order matches the `schema` metadata. All values are returned as strings.\n","items":{"type":"string"},"minItems":23},"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"}},"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. See [Accounts](/api/config-api/endpoints/accounts_config).","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. See [Web Properties](/api/config-api/endpoints/web_properties_config).","example":[122556,987654],"items":{"type":"integer","minimum":1}},"ai_search_engines":{"type":"array","description":"(Optional) list of AI engines to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","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).\nSee [AI Search](/api/config-api/endpoints/ai_search_config).\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). See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["en_US","hant_TW"],"items":{"type":"string","maxLength":7,"minLength":2}},"topics":{"type":"array","description":"(Optional) list of topics to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["marketing automation","website optimization"],"items":{"type":"string"}},"prompts":{"type":"array","description":"(Optional) list of prompts to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","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.\nSee [AI Search](/api/config-api/endpoints/ai_search_config).\n","example":["Education","Purchase"],"items":{"type":"string"}},"personas":{"type":"array","description":"(Optional) list of user-defined personas to filter (e.g., \"android user\", \"developers\"). See [AI Search](/api/config-api/endpoints/ai_search_config).","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"}},"prompts_groups":{"type":"array","description":"(Optional) list of prompt group names to filter (case-insensitive). See\n[AI Search](/api/config-api/endpoints/ai_search_config) with config_type=prompt_groups\nto discover group names.\n","example":["Comparison Prompts"],"items":{"type":"string"}},"prompts_groups_match":{"type":"string","default":"any","description":"(Optional) how `prompts_groups` combines multiple group names: `any` (default) matches\nat least one; `all` matches every listed group.\n","enum":["any","all"],"example":"any"}},"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**`prompt_groups`** (4 columns): prompt_group_id, prompt_group_name, description, parent_group_name (`null` for a top-level group)\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\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- `prompt_groups`: Account-defined groupings of tracked prompts, with each group's parent (if nested).\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","enum":["topics","prompts","prompt_groups","search_engines","locales","languages","brands","personas","intents"],"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"]},"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","x-only-with":{"config_type":["keywords"]}},"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","x-only-with":{"config_type":["keywords"]}},"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"}}},"AccountsConfigRow":{"type":"array","description":"Positional tuple row for accounts configuration results.\nValues are returned as strings in the following order:\n1) organization_id, 2) organization_name, 3) account_id, 4) account_name.\n","items":{"type":"string"},"maxItems":4,"minItems":4},"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. See [Accounts](/api/config-api/endpoints/accounts_config).","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. See [Web Properties](/api/config-api/endpoints/web_properties_config).","example":[122556,987654],"items":{"type":"integer","minimum":1}},"ai_search_engines":{"type":"array","description":"(Optional) list of AI engines to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","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).\nSee [AI Search](/api/config-api/endpoints/ai_search_config).\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). See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["en_US","hant_TW"],"items":{"type":"string","maxLength":7,"minLength":2}},"topics":{"type":"array","description":"(Optional) list of topics to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["marketing automation","website optimization"],"items":{"type":"string"}},"prompts":{"type":"array","description":"(Optional) list of prompts to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","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.\nSee [AI Search](/api/config-api/endpoints/ai_search_config).\n","example":["Education","Purchase"],"items":{"type":"string"}},"personas":{"type":"array","description":"(Optional) list of user-defined personas to filter (e.g., \"android user\", \"developers\"). See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["young adults","developers"],"items":{"type":"string"}},"sentiment_brands":{"type":"array","description":"(Optional) list of sentiment brands to filter (case-insensitive). See [AI Search](/api/config-api/endpoints/ai_search_config).","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"]},"x-ignore-enum-check":true},"sentiment_categories":{"type":"array","description":"(Optional) list of sentiment categories to filter.","example":["price"],"items":{"type":"string","enum":["misc","quality","price","service","user-friendliness","experience","popularity","health","ethics"]},"x-ignore-enum-check":true},"sentiment_source_domains":{"type":"array","description":"(Optional) list of sentiment source domains to filter.","example":["example.com"],"items":{"type":"string"}},"prompts_groups":{"type":"array","description":"(Optional) list of prompt group names to filter (case-insensitive). See\n[AI Search](/api/config-api/endpoints/ai_search_config) with config_type=prompt_groups\nto discover group names.\n","example":["Comparison Prompts"],"items":{"type":"string"}},"prompts_groups_match":{"type":"string","default":"any","description":"(Optional) how `prompts_groups` combines multiple group names: `any` (default) matches\nat least one; `all` matches every listed group.\n","enum":["any","all"],"example":"any"}},"required":["account_id","end_date","start_date"]},"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"},"prompt_group_names":{"type":"string","description":"Comma-separated list of prompt group names the prompt belongs to","example":"Brand Prompts, Competitor Prompts"}}},"AccountsConfigRequest":{"type":"object","description":"Request schema for submitting a new accounts query. Results are automatically\nscoped to the accounts accessible via the API key. Send an empty object (`{}`)\nto use the default limit.\n","properties":{"limit":{"type":"integer","default":100,"description":"(Optional) Maximum number of rows to return for the submitted query.","example":100,"minimum":1}}},"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. See [Accounts](/api/config-api/endpoints/accounts_config).","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. See [Web Properties](/api/config-api/endpoints/web_properties_config).","example":[122556,987654],"items":{"type":"integer","minimum":1}},"ai_search_engines":{"type":"array","description":"(Optional) list of AI engines to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","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).\nSee [AI Search](/api/config-api/endpoints/ai_search_config).\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). See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["en_US","hant_TW"],"items":{"type":"string","maxLength":7,"minLength":2}},"topics":{"type":"array","description":"(Optional) list of topics to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["marketing automation","website optimization"],"items":{"type":"string"}},"prompts":{"type":"array","description":"(Optional) list of prompts to filter. See [AI Search](/api/config-api/endpoints/ai_search_config).","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.\nSee [AI Search](/api/config-api/endpoints/ai_search_config).\n","example":["Education","Purchase"],"items":{"type":"string"}},"personas":{"type":"array","description":"(Optional) list of user-defined personas to filter (e.g., \"android user\", \"developers\"). See [AI Search](/api/config-api/endpoints/ai_search_config).","example":["young adults","developers"],"items":{"type":"string"}},"brand_or_product_names":{"type":"array","description":"(Optional) list of brands and products to filter (case-insensitive). See [AI Search](/api/config-api/endpoints/ai_search_config).","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"}},"prompts_groups":{"type":"array","description":"(Optional) list of prompt group names to filter (case-insensitive). See\n[AI Search](/api/config-api/endpoints/ai_search_config) with config_type=prompt_groups\nto discover group names.\n","example":["Comparison Prompts"],"items":{"type":"string"}},"prompts_groups_match":{"type":"string","default":"any","description":"(Optional) how `prompts_groups` combines multiple group names: `any` (default) matches\nat least one; `all` matches every listed group.\n","enum":["any","all"],"example":"any"}},"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"},"ApiToken":{"type":"http","description":"Conductor API token, sent as `Bearer <your-api-token>`. Generate a token from Integrations > API > Create API Token.","scheme":"bearer"}}}}