> ## 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
> Execute an asynchronous query against AI search configuration metadata.
The response schema varies based on the `config_type` parameter.
This endpoint follows the asynchronous query flow.
### Config Types:
- **`topics`**: Tracked AI search topics with status, search engine, frequency, locale, and prompt count. Supports optional filters: `topic_status`, `prompt_status`.
- **`prompts`**: Individual prompts with type, status, topic, search engine, locale, language, intent, and persona. Supports optional filters: `topic_status`, `prompt_status`, `topics`.
- **`search_engines`**: Distinct AI search engines in use for tracked topics.
- **`locales`**: Distinct locales in use for tracked topics.
- **`languages`**: Distinct languages in use for tracked topics.
- **`brands`**: Tracked brands with associated owned and comparison web properties.
- **`personas`**: Personas defined for the account.
- **`intents`**: Distinct intents in use for tracked prompts.
- **`sentiment_categories`**: Distinct sentiment categories observed in AI search results.
### 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_config
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_config:
post:
tags:
- Configuration
- AI Search
summary: Query AI Search Configuration (Async)
description: >
Execute an asynchronous query against AI search configuration metadata.
The response schema varies based on the `config_type` parameter.
This endpoint follows the asynchronous query flow.
### Config Types:
- **`topics`**: Tracked AI search topics with status, search engine,
frequency, locale, and prompt count. Supports optional filters:
`topic_status`, `prompt_status`.
- **`prompts`**: Individual prompts with type, status, topic, search
engine, locale, language, intent, and persona. Supports optional
filters: `topic_status`, `prompt_status`, `topics`.
- **`search_engines`**: Distinct AI search engines in use for tracked
topics.
- **`locales`**: Distinct locales in use for tracked topics.
- **`languages`**: Distinct languages in use for tracked topics.
- **`brands`**: Tracked brands with associated owned and comparison web
properties.
- **`personas`**: Personas defined for the account.
- **`intents`**: Distinct intents in use for tracked prompts.
- **`sentiment_categories`**: Distinct sentiment categories observed in
AI search results.
### 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: 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.
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:
topics:
summary: Get topics for account
value:
config_type: topics
account_id: 101
topic_status: ACTIVE
prompt_status: ACTIVE
prompts:
summary: Get prompts with topic info for account
value:
config_type: prompts
account_id: 101
topic_status: ACTIVE
prompt_status: ACTIVE
topics: ai search,seo tools
limit: 100
search_engines:
summary: Get tracked AI search engines
value:
config_type: search_engines
account_id: 101
locales:
summary: Get locales used by tracked topics
value:
config_type: locales
account_id: 101
languages:
summary: Get languages in use for tracked topics
value:
config_type: languages
account_id: 101
brands:
summary: Get tracked brands with owned and comparison web properties
value:
config_type: brands
account_id: 101
personas:
summary: Get personas for account
value:
config_type: personas
account_id: 101
intents:
summary: Get intents in use
value:
config_type: intents
account_id: 101
sentiment_categories:
summary: Get sentiment categories in use
value:
config_type: sentiment_categories
account_id: 101
required: true
responses:
'200':
description: >
Query completed successfully (returned when polling with
queryExecutionId).
The response `schema` and `results` tuple structure vary by
`config_type` — see Config Types above.
The default schema example below shows the `prompts` config_type
response.
Named 200 response examples are also provided for each supported
`config_type`.
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.
Available only when `executionState` is `COMPLETED`.
Column order depends on `config_type` — use the `schema`
field to interpret positions.
items:
$ref: '#/components/schemas/AiSearchConfigRow'
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.
examples:
topics:
summary: Topics response
value:
results:
- - ai seo tools
- ACTIVE
- ChatGPT (Search)
- WEEKLY
- US
- '12'
schema:
- name: topic_name
type: string
- name: topic_status
type: string
- name: search_engine
type: string
- name: tracking_frequency
type: string
description: 'Collection frequency. One of: DAILY, WEEKLY, MONTHLY.'
- name: locode
type: string
- name: prompt_count
type: integer
executionState: COMPLETED
executionId: enga:abc12345-1111-2222-3333-555555555551
requestId: req-201
totalRowCount: 1
prompts:
summary: Prompts response
value:
results:
- - best seo practices for 2025
- unbranded
- ACTIVE
- '2025-01-01'
- WEEKLY
- ai seo tools
- ChatGPT (Search)
- US
- English
- Education
- seo
schema:
- name: prompt
type: string
- name: prompt_type
type: string
- name: prompt_status
type: string
- name: tracking_start_date
type: date
- name: tracking_frequency
type: string
description: 'Collection frequency. One of: DAILY, WEEKLY, MONTHLY.'
- name: topic_name
type: string
- name: search_engine
type: string
- name: locode
type: string
- name: language
type: string
- name: intent
type: string
- name: persona
type: string
executionState: COMPLETED
executionId: enga:abc12345-1111-2222-3333-444444444444
requestId: req-123
nextPageId: 87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==
totalRowCount: 1000
search_engines:
summary: Search engines response
value:
results:
- - ChatGPT (Search)
- - Perplexity
schema:
- name: name
type: string
executionState: COMPLETED
executionId: enga:abc12345-1111-2222-3333-555555555552
requestId: req-202
totalRowCount: 2
locales:
summary: Locales response
value:
results:
- - US
- - GB
schema:
- name: locode
type: string
executionState: COMPLETED
executionId: enga:abc12345-1111-2222-3333-555555555553
requestId: req-203
totalRowCount: 2
languages:
summary: Languages response
value:
results:
- - English
- - Spanish
schema:
- name: name
type: string
executionState: COMPLETED
executionId: enga:abc12345-1111-2222-3333-555555555554
requestId: req-204
totalRowCount: 2
brands:
summary: Brands response (owned and comparison web properties)
value:
results:
- - Conductor
- '456'
- conductor.com
- 'true'
- - Searchlight
- '789'
- searchlight.com
- 'false'
schema:
- name: brand_name
type: string
- name: web_property_id
type: integer
- name: web_property_name
type: string
- name: is_owned
type: boolean
description: >-
True when the web property is account-owned; false
when it is a comparison web property.
executionState: COMPLETED
executionId: enga:abc12345-1111-2222-3333-555555555555
requestId: req-205
totalRowCount: 2
personas:
summary: Personas response
value:
results:
- - seo
- SEO practitioner persona
- - executive
- Executive stakeholder persona
schema:
- name: name
type: string
- name: description
type: string
executionState: COMPLETED
executionId: enga:abc12345-1111-2222-3333-555555555556
requestId: req-206
totalRowCount: 2
intents:
summary: Intents response
value:
results:
- - Education
- - Comparison
schema:
- name: name
type: string
executionState: COMPLETED
executionId: enga:abc12345-1111-2222-3333-555555555557
requestId: req-207
totalRowCount: 2
sentiment_categories:
summary: Sentiment categories response
value:
results:
- - pricing
- - support
schema:
- name: sentiment_category
type: string
executionState: COMPLETED
executionId: enga:abc12345-1111-2222-3333-555555555558
requestId: req-208
totalRowCount: 2
'202':
description: Query accepted and is being processed asynchronously
content:
application/json:
schema:
type: object
example:
results: []
schema: []
executionState: IN_PROGRESS
executionId: enga:b3d8a1c7-9f2e-4d6a-a5b1-8c4e2f7d9a03
requestId: 4e2c8f19-7a3d-4b5e-9c1f-6d8a2e4b7f30
properties:
results:
type: array
description: |
Empty array when `executionState` is `IN_PROGRESS`.
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: >-
config_type must be one of: topics, prompts, search_engines,
locales, languages, brands, personas, intents,
sentiment_categories
properties:
error:
type: string
description: Error code or identifier
message:
type: string
description: Detailed error message
'401':
description: Unauthorized - API key missing or invalid
'429':
description: Too many requests
'500':
description: Internal server error
components:
schemas:
AiSearchConfigRequest:
type: object
description: >
Request schema for submitting a new AI search configuration query.
The `config_type` determines which data is returned and which optional
filters apply.
properties:
config_type:
type: string
description: >
Type of AI search configuration data to return:
- `topics`: Tracked topics with status, search engine, frequency,
locale, and prompt count.
- `prompts`: Individual prompts with type, status, topic, search
engine, locale, language, intent, and persona.
- `search_engines`: Distinct AI search engines used by tracked
topics.
- `locales`: Distinct locales used by tracked topics.
- `languages`: Distinct languages used by tracked topics.
- `brands`: Tracked brands with associated owned and comparison web
properties.
- `personas`: Personas defined for the account.
- `intents`: Distinct intents used by tracked prompts.
- `sentiment_categories`: Distinct sentiment categories observed in
AI search results.
enum:
- topics
- prompts
- search_engines
- locales
- languages
- brands
- personas
- intents
- sentiment_categories
example: prompts
account_id:
type: integer
description: Required account ID to filter results.
example: 101
minimum: 1
topic_status:
type: string
default: ACTIVE
description: >
(Optional, `topics` and `prompts` only) Comma-separated topic
statuses to include.
Accepted values: `ACTIVE`, `INACTIVE`. An empty string disables the
filter. Default is `ACTIVE`.
example: ACTIVE
prompt_status:
type: string
default: ACTIVE
description: >
(Optional, `topics` and `prompts` only) Comma-separated prompt
statuses to include.
Accepted values: `ACTIVE`, `INACTIVE`. An empty string disables the
filter. Default is `ACTIVE`.
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
AiSearchConfigRow:
type: array
description: >
Positional tuple row. Column order depends on `config_type`:
**`topics`** (6 columns): topic_name, topic_status, search_engine,
tracking_frequency (DAILY, WEEKLY, or MONTHLY), locode, prompt_count
**`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
**`search_engines`** (1 column): name
**`locales`** (1 column): locode
**`languages`** (1 column): name
**`brands`** (4 columns): brand_name, web_property_id,
web_property_name, is_owned (`true` for owned, `false` for comparison)
**`personas`** (2 columns): name, description
**`intents`** (1 column): name
**`sentiment_categories`** (1 column): sentiment_category
Use the `schema` field in the response to interpret column positions.
items:
type: string
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
````