> ## 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.
# Highest Ranking URL per Keyword
> Execute an asynchronous query against the keyword rankings dataset to get highest ranking URL per keyword.
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/highest_ranking_url_per_keyword
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/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.
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: 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.
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: >-
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.
Available only when `executionState` is `COMPLETED`.
items:
$ref: '#/components/schemas/HighestRankingUrlPerKeywordRow'
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:c4e9b2d8-a03f-4e7b-b6c2-9d5f3a8e1b04
requestId: 5f3d9a20-8b4e-4c6f-ad2a-7e9b3f5c8a41
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:
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.
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.
Maximum date range is 92 days.
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).
If `collection_frequency` is `WEEKLY` or not set, this must be a
Saturday.
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`.
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.
example:
- Brand
- Non-Brand
- Category
items:
type: string
web_property_ids:
type: array
description: (Optional) list of web property IDs to filter results.
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).
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.
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
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
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.
items:
type: string
maxItems: 31
minItems: 26
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
````