> ## 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 - Brands
> Execute a query to retrieve brand-focused data from AI search responses, including only own brand entities.
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.
### 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.
## OpenAPI
````yaml POST /data-api/v1/async/ai_search_brands
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. Authentication
is handled through the API Gateway using an API key and request signature
system that ensures secure access to the data.
Authentication with API key and signature
All endpoints require 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 when
complete or 202 Accepted if still running
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" or "COMPLETED")
- `nextPageId` Token for retrieving the next page of results when available
#### Response Codes
- **202 Accepted**: Query is still running (executionState = "IN_PROGRESS")
- **200 OK**: Query completed successfully (executionState = "COMPLETED")
contact:
name: Data Platform Team
email: data-platform@conductor.com
version: 1.0.0
servers:
- url: https://api-universal.conductor.com
security:
- ApiKeyQuery: []
SigQuery: []
tags:
- name: Traditional Search / Foundational
description: Core keyword ranking and SERP data from traditional search engines
- name: Traditional Search / Derived
description: >-
Derived metrics from traditional search data, such as highest ranking URL
per keyword
- name: AI / Foundational
description: >-
Foundational data from AI search engines including brand mentions,
citations, and sentiment analysis
paths:
/data-api/v1/async/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.
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.
### 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: 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.
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
required: true
responses:
'200':
description: Successful query execution
content:
application/json:
schema:
type: object
example:
results:
- - Conductor Organization
- base64-encoded-organization-id
- Conductor Account
- '123'
- conductor.com
- '456'
- '2026-01-11'
- '2026-01-17'
- WEEKLY
- US
- en_US
- chatgpt
- best AEO and GEO platforms
- best AEO and GEO platforms 2026 - complete guide
- unbranded
- Educational
- broad audience
- Conductor
- brand
- you
- 'true'
- 'true'
schema:
- name: organization_name
type: string
- name: organization_id
type: string
- name: account_name
type: string
- name: account_id
type: integer
- name: web_property_name
type: string
- name: web_property_id
type: integer
- name: time_period_start
type: date
- name: time_period_end
type: date
- name: collection_frequency
type: string
- name: locode
type: string
- name: language
type: string
- name: ai_search_engine
type: string
- name: topic
type: string
- name: prompt
type: string
- name: prompt_type
type: string
- name: intent
type: string
- name: persona
type: string
- name: brand_or_product_name
type: string
- name: brand_or_product_entity_type
type: string
- name: brand_or_product_attribution
type: string
- name: ai_response_collected
type: boolean
- name: web_search_triggered
type: boolean
executionState: COMPLETED
executionId: enga:f47ac10b-58cc-4372-a567-0e02b2c3d479
requestId: 9e3b7c12-f4a5-48d1-b6e9-0c32d5a8e1b4
nextPageId: 87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==
totalRowCount: 1000
properties:
results:
type: array
description: >
List of query results. Each item is a positional tuple
row.
Available only when `executionState` is `COMPLETED`.
items:
$ref: '#/components/schemas/AiSearchBrandsRow'
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.
- `FAILED`: The query failed. Check the error message if
available.
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).
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.
- `FAILED`: The query failed. Check the error message if
available.
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).
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
'429':
description: Too many requests
'500':
description: Internal server error
components:
schemas:
AiSearchBrandsRequest:
type: object
description: Request schema for submitting a new AI Search Brand data query.
properties:
account_id:
type: integer
description: Required account ID to filter results.
example: 101
minimum: 1
start_date:
type: string
format: date
description: >
Start date of the time period (yyyy-MM-dd).
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
web_property_ids:
type: array
description: (Optional) list of web property IDs to filter results.
example:
- 122556
- 987654
items:
type: integer
minimum: 1
ai_search_engines:
type: array
description: (Optional) list of AI engines to filter.
example:
- chatgptsearch
- perplexity
items:
type: string
locodes:
type: array
description: >
(Optional) list of locodes to filter (case-insensitive). Based on
ISO names from a predefined dictionary.
A locode can represent a country ("US"), city ("US NYC"), state
("PL-02"), or a specific location (e.g., an airport).
example:
- US
- CA
- US NYC
- US-TX
items:
type: string
maxLength: 12
minLength: 2
languages:
type: array
description: >-
(Optional) list of search engine language codes to filter
(case-insensitive; e.g., en_US, hant_TW).
example:
- en_US
- hant_TW
items:
type: string
maxLength: 7
minLength: 2
topics:
type: array
description: (Optional) list of topics to filter.
example:
- marketing automation
- website optimization
items:
type: string
prompts:
type: array
description: (Optional) list of prompts to filter.
example:
- best crm
- top crm
items:
type: string
prompt_type:
type: string
description: (Optional) indicates whether the prompt is branded or unbranded.
enum:
- branded
- unbranded
example: branded
intents:
type: array
description: >
(Optional) list of intents to filter. Options include:
Education, Brand/Service Navigation, Pricing, Support,
Recommendations, Comparison, Purchase, Other.
example:
- Education
- Purchase
items:
type: string
personas:
type: array
description: >-
(Optional) list of user-defined personas to filter (e.g., "android
user", "developers").
example:
- young adults
- developers
items:
type: string
brand_or_product_names:
type: array
description: (Optional) list of brands and products to filter (case-insensitive).
example:
- Conductor
- Conductor AI
items:
type: string
brand_or_product_attributions:
type: array
description: >-
(Optional) list of brand or product ownership to filter
(case-insensitive).
example:
- You
- Partner
- SEO Competitor
- Other
items:
type: string
required:
- account_id
- end_date
- start_date
AiSearchBrandsRow:
type: array
description: >
Positional tuple row for AI Search Brand results. Column order matches
the `schema` metadata. All values are returned as strings.
items:
type: string
minItems: 22
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
````