> ## Documentation Index > Fetch the complete documentation index at: https://www.conductor.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # AI Search - Fan Out > Retrieve fan out query data—the sub-searches an AI engine runs before answering a tracked prompt—with Conductor's asynchronous Data API. Submit, poll, and fetch results. ## Change Log * **2026-08-28 · Added** — AI Search Fan Out endpoint, returning one row per individual fan out query an AI engine runs before answering a tracked prompt. ## OpenAPI ````yaml POST /data-api/v1/async/ai_search_fan_out openapi: 3.1.0 info: title: Conductor Data API description: > ## API Gateway Usage All API requests must be made to the API Gateway URL (check Servers section below), not directly to the Data API. The API Gateway handles authentication, rate limiting, and routing to the appropriate backend services. ## Authentication The Data API requires secure authentication for all requests, made through the API Gateway. **Recommended: Conductor API token** Send your Conductor API token in the `Authorization` header: ``` Authorization: Bearer cond_ ``` Generate a token from Integrations > API > Create API Token in the Conductor app.
Legacy: API key and signature (still supported) Conductor still supports existing connections using this legacy method. We recommend new connections use the API token method described above. All endpoints accept authentication through the API Gateway using ALL of the following elements together: 1. API Key as a query parameter: `apiKey=` 2. Request signature as a query parameter: `sig=` The signature is computed using your API key and secret. Example Python code for computing the signature: ```python import hashlib import time def compute_signature(api_key: str, secret: str) -> str: # Create the string to sign (api_key + secret + timestamp) timestamp = str(int(time.time())) # Unix timestamp in seconds string_to_sign = f"{api_key}{secret}{timestamp}" # Compute MD5 signature signature = hashlib.md5(string_to_sign.encode('utf-8')).hexdigest() return signature # Example usage: api_key = "your-api-key" secret = "your-secret" signature = compute_signature(api_key, secret) url = f"https://api-universal.conductor.com/data-api/v1/keyword_rankings?apiKey={api_key}&sig={signature}" ```
## Asynchronous Queries The Data API supports asynchronous query execution for potentially long-running queries. This allows clients to submit a query and retrieve results later, rather than waiting for the entire query to complete. Asynchronous endpoints are marked with **(Async)** in their descriptions.
Asynchronous Query Details #### Asynchronous Query Flow 1. **Initial Request**: Submit query parameters - returns 202 Accepted with `executionId` 2. **Polling**: Use `executionId` to poll for results - returns 200 OK with executionState = "IN_PROGRESS" while running, and with the results once "COMPLETED" 3. **Pagination**: Use `nextPageId` from completed results to get additional pages #### Request Parameters - For initial submission: Include all required query parameters specific to the endpoint - For polling: Include `executionId` (and optionally `pageSize`, `nextPageId` for pagination) #### Response Fields - `executionId` Unique identifier for tracking the query execution - `executionState` Status of the query ("IN_PROGRESS", "COMPLETED", or "FAILED" with a 409) - `nextPageId` Token for retrieving the next page of results when available - `error` and `message` Only on a failed query: a stable error code, and what to do next #### Response Codes - **202 Accepted**: Query submitted and still running (executionState = "IN_PROGRESS") - **200 OK**: Poll of a running query (executionState = "IN_PROGRESS"), or of a completed one with its results (executionState = "COMPLETED") - **404 Not Found**: No query execution matches the `executionId`, or it has expired. Submit the query again. - **409 Conflict**: The query failed or was cancelled (executionState = "FAILED"). This is final: polling again returns the same answer. `error` is `QUERY_RESOURCES_EXHAUSTED` (narrow the request before submitting it again; the identical request fails the same way), `QUERY_CANCELLED` or `QUERY_FAILED` (submit it again)
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/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. This endpoint follows the asynchronous query flow. ### Usage Patterns: - **Submit**: Create a query (Initial request). Returns `executionId`. - **Poll**: Use `executionId` to check status. Returns 200 with results when `COMPLETED`. - **Paginate**: Use `executionId` and `nextPageId` from the previous response. - **Failure**: If the query fails, polling returns `409` with `executionState: FAILED`, an `error` code and a `message` saying what to do next. Polling again returns the same answer. ### Rate Limits: - **Submit**: 40 req/min (Hard), 5 req/min (Recommended). - **Poll/Paginate**: 5000 req/min (Hard), 1000 req/min (Recommended). ### Sequential Pagination: - 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. 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. Note: Pagination must be done sequentially as `nextPageId` depends on the current page. 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. Maximum: 1000. Default: 1000. 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. Available only when `executionState` is `COMPLETED`. items: $ref: '#/components/schemas/AiSearchFanOutRow' executionState: type: string description: > Current execution state of the query: - `IN_PROGRESS`: The query is still running. Poll again later. - `COMPLETED`: The query finished successfully. Results are available. enum: - IN_PROGRESS - COMPLETED 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). If `null`, there are no more pages available. 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`. Available once `executionState` becomes `COMPLETED`. items: type: object executionState: type: string description: > Current execution state of the query: - `IN_PROGRESS`: The query is still running. Poll again later. - `COMPLETED`: The query finished successfully. Results are available. enum: - IN_PROGRESS - COMPLETED 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). If `null`, there are no more pages available. 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 '404': description: > No query execution matches the `executionId`: it was never issued, or it is older than its 7-day validity. Submit the query again to get a new `executionId`. content: application/json: schema: type: object example: error: Execution not found message: >- No query execution matches this executionId, or it has expired. Submit the query again to get a new executionId. properties: error: type: string description: Error identifier message: type: string description: Detailed error message '409': description: > The query failed or was cancelled. This is the final answer for this execution: polling it again returns the same response. `error` says why and `message` what to do next. Submitting the request again starts a new execution, except after `QUERY_RESOURCES_EXHAUSTED`: the identical request would fail the same way, so for up to 2 hours it is answered with this same failure. Narrow the request instead (for example a shorter date range, or fewer accounts or web properties). content: application/json: schema: type: object example: results: [] schema: [] executionState: FAILED executionId: enga:f47ac10b-58cc-4372-a567-0e02b2c3d479 requestId: 9e3b7c12-f4a5-48d1-b6e9-0c32d5a8e1b4 error: QUERY_RESOURCES_EXHAUSTED message: >- The query needed more resources than a single request allows. Narrow it (for example a shorter date range, or fewer accounts or web properties) and submit it again. properties: results: type: array description: Always empty. items: type: object schema: type: array description: Always empty. items: type: object executionState: type: string description: The query failed or was cancelled. enum: - FAILED executionId: type: string description: The execution that failed. requestId: type: string description: >- Unique identifier for the HTTP request, useful for support and debugging. nextPageId: type: string description: Always `null`. A failed query has no pages. totalRowCount: type: integer format: int64 description: Always `null`. error: type: string description: > Why the query failed: - `QUERY_RESOURCES_EXHAUSTED`: the request needs more resources than a single query allows. Narrow it before submitting again; the identical request fails the same way. - `QUERY_CANCELLED`: the query was cancelled before it finished. Submit it again. - `QUERY_FAILED`: any other failure. Submit it again; if it keeps failing, contact support with the `executionId`. enum: - QUERY_RESOURCES_EXHAUSTED - QUERY_CANCELLED - QUERY_FAILED message: type: string description: What happened and what to do next, in plain language. '429': description: Too many requests '500': description: Internal server error components: schemas: 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 x-integer-only: true start_date: type: string format: date description: > Start date of the time period (yyyy-MM-dd). If `collection_frequency` is `WEEKLY` or not set, this must be a Sunday. If `collection_frequency` is `MONTHLY`, this must be the first day of the month. 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). If `collection_frequency` is `WEEKLY` or not set, this must be a Saturday. If `collection_frequency` is `MONTHLY`, this must be the last day of the month. 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. Must be between 1 and 1,000 inclusive; a value outside that range is rejected with a 400. 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. A locode can represent a country ("US"), city ("US NYC"), state ("PL-02"), or a specific location (e.g., an airport). 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) 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: Education, Brand/Service Navigation, Pricing, Support, Recommendations, Comparison, Purchase, Other. See [AI Search](/api/config-api/endpoints/ai_search_config). 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 [AI Search](/api/config-api/endpoints/ai_search_config) with config_type=prompt_groups to discover group names. 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 at least one; `all` matches every listed group. enum: - any - all example: any required: - account_id - end_date - start_date 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. items: type: string minItems: 23 securitySchemes: ApiToken: type: http description: >- Conductor API token, sent as `Bearer `. Generate a token from Integrations > API > Create API Token. scheme: bearer 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 ````