> ## 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.
# Keyword Search
> Execute an asynchronous query against keyword tracking configuration metadata.
The response schema varies based on the `config_type` parameter.
This endpoint follows the asynchronous query flow.
### Config Types:
- **`keywords`**: Tracked keywords with status, groups, locale, search engine, and device. Supports optional filters: `web_property_id`, `keyword_group_id`, `keyword_status`.
- **`keyword_groups`**: Keyword groups defined for the account.
- **`search_engines`**: Distinct search engines in use for tracked keywords.
- **`devices`**: Distinct devices in use for tracked keywords.
- **`locales`**: Distinct locales in use for tracked keywords.
### 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/keyword_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/keyword_search_config:
post:
tags:
- Configuration
- Traditional
summary: Query Keyword Configuration (Async)
description: >
Execute an asynchronous query against keyword tracking configuration
metadata.
The response schema varies based on the `config_type` parameter.
This endpoint follows the asynchronous query flow.
### Config Types:
- **`keywords`**: Tracked keywords with status, groups, locale, search
engine, and device. Supports optional filters: `web_property_id`,
`keyword_group_id`, `keyword_status`.
- **`keyword_groups`**: Keyword groups defined for the account.
- **`search_engines`**: Distinct search engines in use for tracked
keywords.
- **`devices`**: Distinct devices in use for tracked keywords.
- **`locales`**: Distinct locales in use for tracked keywords.
### 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: 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.
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:
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).
The response `schema` and `results` tuple structure vary by
`config_type` — see Config Types above.
The default schema example below shows the `keywords` config_type
response.
Named 200 response examples are also provided for each supported
`config_type`.
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.
Available only when `executionState` is `COMPLETED`.
Column order depends on `config_type` — use the `schema`
field to interpret positions.
items:
$ref: '#/components/schemas/KeywordSearchConfigRow'
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:
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`.
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: 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
components:
schemas:
KeywordSearchConfigRequest:
type: object
description: >
Request schema for submitting a new keyword configuration query.
The `config_type` determines which data is returned and which optional
filters apply.
properties:
config_type:
type: string
description: >
Type of keyword configuration data to return:
- `keywords`: All tracked keywords with status, groups, locale,
search engine, and device.
- `keyword_groups`: Keyword groups defined for the account.
- `search_engines`: Distinct search engines used by tracked
keywords.
- `devices`: Distinct devices used by tracked keywords.
- `locales`: Distinct locales used by tracked keywords.
enum:
- keywords
- keyword_groups
- search_engines
- devices
- locales
example: keywords
account_id:
type: integer
description: Required account ID to filter results.
example: 101
minimum: 1
web_property_id:
type: integer
description: >-
(Optional, `keywords` only) Filter results to a specific web
property.
example: 456
keyword_group_id:
type: string
description: >-
(Optional, `keywords` only) Filter results to keywords in a specific
keyword group.
example: '995895'
keyword_status:
type: string
default: ACTIVE
description: >
(Optional, `keywords` only) Comma-separated keyword statuses to
include.
Accepted values: `ACTIVE`, `INACTIVE`. An empty string disables the
filter. Default is `ACTIVE`.
example: ACTIVE
limit:
type: integer
default: 100
description: Maximum number of rows to return for the submitted query.
example: 100
minimum: 1
required:
- account_id
- config_type
KeywordSearchConfigRow:
type: array
description: >
Positional tuple row. Column order depends on `config_type`:
**`keywords`** (8 columns): web_property_id, keyword, status,
keyword_groups, tracking_start_date, locale, kw_search_engine, device
**`keyword_groups`** (2 columns): keyword_group_id, keyword_group_name
**`search_engines`** (1 column): name
**`devices`** (1 column): name
**`locales`** (1 column): locode
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
````