Conductor's Data API (v1)

Product

CreatorWhat is Conductor Creator?
IntelligenceWhat is Conductor Intelligence?
MonitoringWhat is Conductor Monitoring?

Plan

What is my plan?
Essentials
Standard
Growth
Professional
Enterprise
+ Add-on Required
Alpha

Getting Started

Overview

Conductor’s Data API empowers organization's like yours to seamlessly integrate traditional and search insights directly into your existing data ecosystems. By automating data delivery, gain rapid, on-demand access to the metrics that matter most—powering custom dashboards, business intelligence tools, and cross-channel reporting without manual effort. 

This API unlocks flexible, secure data sharing at scale, ensuring everyone in your organization is equipped with timely, actionable intelligence. Accelerate decision-making and drive measurable results by connecting Conductor’s data wherever their teams work best.

Note

Conductor provides APIs for several different uses across its Conductor Monitoring and Conductor Intelligence products. This article describes Conductor's Data API, which replaces the legacy Conductor Intelligence Reporting API. If you are looking for information about a different API offering, consider the following articles:

 

Resources

The endpoints documented below let you analyze how your brand appears in traditional organic search and in AI-generated search responses across engines like Google, ChatGPT, Perplexity, Google AIO, and more. There are five endpoints:

/data-api/v1/async/keyword_rankings

What It Includes: Rank and contextual data for your tracked keywords

Key Question It Answers: “For which tracked keywords do I appear in search?”

/data-api/v1/async/highest_ranking_url_per_keyword

What It Includes: Rank and contextual data for your highest-ranking results

Key Question It Answers: "For which tracked keywords do I rank best in search?”

/data-api/v1/async/ai_search_brands

What It Includes: Brand and product mentions in AI responses

Key Question It Answers: "Which brands are AI engines recommending for my topics?"

/data-api/v1/async/ai_search_citations

What It Includes: URLs and domains cited as sources

Key Question It Answers: "Which websites are AI engines citing as sources?"

/data-api/v1/async/ai_search_sentiments

What It Includes: Sentiment analysis of brand mentions

Key Question It Answers: “What is AI saying about my brand — positive, negative, or neutral?”

Authentication

Conductor uses a signed URL parameter to securely authenticate users. To create this signed parameter, you'll need the following building blocks:

  • An API Key
  • An API Secret
  • The current time (expressed as seconds since the UNIX epoch: unixEpochTimeSeconds)

Additionally, you'll need to add a header to your request that will allow access to this API.

We'll deal with the first two building blocks of the signed URL parameter before moving on to the third. Then we'll cover how to use all of them to build your full request, below. Finally, we'll cover the required request header.

1. Generate your Conductor API Key and Secret

If you want to build connections with Conductor's public API, you'll need to generate a Key and Secret to use to make calls to the API.

  1. Click here or follow the path Integrations > API in Conductor.
  2. Click Generate API Key.
    Generate Key.png
  3. Click to copy your API Key and Secret to use in building your API calls.
    Key and secret.png

Temporarily save these values so you can reference them below—but be sure to delete or erase your notes after. You can always retrieve these values from the platform again.

2. Generate Your Signed URL Parameter

A signature is a one-way MD5 hash of three values:

  • A user's API key
  • A user's Secret
  • The current time expressed as seconds since the UNIX epoch (unixEpochTimeSeconds)

Your programming environment must provide the ability to do the following, which is part of the standard library for most programming languages:

  • Get the current UNIX time in seconds.
  • Compute MD5 hashes.

Note that, to allow for reasonable clock drift between your servers and Conductor's servers, the Conductor API considers a signature matching if it was signed within 5 minutes of the time on Conductor's servers.

Code Example

Review the Python sample below 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)
 

3. Build Your Request URL

You can build request URLs based on the building blocks you now have:

  • Base URL: https://api-universal.conductor.com
  • Request Path: This is your desired endpoint. Each endpoint is documented below.
  • Query Parameters:
    • apiKey
      This is your API Key generated in the platform.
    • sig
      This is the signature you generated above.
https://api-universal.conductor.com/{REQUEST PATH}?apiKey={YOUR API KEY}&sig={YOUR SIGNATURE}

4. Include the x-api-gateway-key Request Header

Finally, you'll need to add the following header to your request: x-api-gateway-key

For its value, assign the API Key you generated above. Thus, for example:

'x-api-gateway-key': '{YOUR API KEY}'

Use this request URL and the request header to authenticate your calls to the Data API.

Asynchronous Request Requirement

Calls made to Conductor's Data API require asynchronous requests. The asynchronous request workflow follows these steps:

  1. You make an initial request to an endpoint.
  2. Conductor returns an initial 202 response that includes an executionId.
  3. You poll the endpoint with the executionId and any optional pagination included in your request body.

Pagination

Include pageSize and nextPageId in your request body as you make asynchronous polling calls.

Quick Start

Here is a complete example Python script you can use to fetch brand data from the /data-api-v1/async/ai_search_brands endpoint described below.

import hashlib, time, requests
from urllib.parse import urlencode

# --- Your credentials ---
API_KEY  = "your_api_key_here"
SECRET   = "your_secret_here"
ACCOUNT  = "your_account_id"

# --- Generate auth ---
epoch = str(int(time.time()))
sig = hashlib.md5((API_KEY + SECRET + epoch).encode()).hexdigest()

url = f"https://api-universal.conductor.com/data-api/v1/async/ai_search_brands?apiKey={API_KEY}&sig={sig}"

headers = {
    "x-api-key": API_KEY,
    "x-api-gateway-key": API_KEY,
    "Content-Type": "application/json",
}

body = {
    "account_id": ACCOUNT,
    "start_date": "2026-02-01",
    "end_date": "2026-02-07",
}

# --- Submit and poll ---
resp = requests.post(url, headers=headers, json=body)
data = resp.json()
execution_id = data.get("executionId")

while data.get("executionState") == "IN_PROGRESS":
    time.sleep(3)
    # Re-generate auth (signature is time-sensitive)
    epoch = str(int(time.time()))
    sig = hashlib.md5((API_KEY + SECRET + epoch).encode()).hexdigest()
    url = f"https://api-universal.conductor.com/data-api/v1/async/ai_search_brands?apiKey={API_KEY}&sig={sig}"
    body["executionId"] = execution_id
    resp = requests.post(url, headers=headers, json=body)
    data = resp.json()

# --- Parse results ---
schema = data["schema"]
field_names = [f["name"] for f in schema]
rows = [dict(zip(field_names, row)) for row in data["results"]]

print(f"Got {len(rows)} rows")
for row in rows[:3]:
    print(row["brand_or_product_name"], "-", row["prompt"])

Data API and Platform Configuration

Base URL

Conductor Data API is available on the following URL:

https://api-universal.conductor.com

AI and Organic Search Visibility Resources

These datasets provide enterprise-level insights into how your brand appears across both traditional search engine results pages (SERPs) and modern AI-driven search experiences. These endpoints allow marketing teams to track keyword rankings, monitor highest-performing pages, and analyze brand visibility, citations, and sentiment within AI search engines.

Get Foundational Keyword Data

/data-api/v1/async/keyword_rankings

This endpoint returns rank data for your tracked keywords across all accounts your organization manages in Conductor. This data is the foundation for organic search performance analysis, enabling teams to track visibility and growth over time.

Request Parameters

  • For initial requests: Include parameters from the list below.
  • For asynchronous polling: Include executionId and optional pagination parameters
    (pageSize, nextPageId).

account_id

Type: string | Example: "12345"

Required. The unique identifier(s) for the Conductor account(s) you are requesting data for.

start_date

Type: string (YYYY-MM-DD) | Example: "2026-01-25"

Required. The start date for the reporting period in YYYY-MM-DD format.

end_date

Type: string (YYYY-MM-DD) | Example: "2026-01-26"

Required. The end date for the reporting period in YYYY-MM-DD format.

collection_frequency

Type: string (enum) | Example: "DAILY"

Optional. The frequency at which rank data is collected. Supported values typically include DAILY or WEEKLY.

web_property_ids

Type: array[number] | Example: [12345, 78901]

Optional. An array of unique identifiers for the web properties to include in the request.

search_engine_names

Type: array[string] | Example: ["GOOGLE_en_US"]

Optional. An array of search engine identifiers (e.g., GOOGLE_en_US) to filter the results.

devices

Type: array[string] | Example: ["DESKTOP", "SMARTPHONE"]

Optional. Filters the results by specific device types. Supported values include DESKTOP, SMARTPHONE, and TABLET.

locodes

Type: array[string] | Example: ["US", "DE"]

Optional. An array of location codes used to filter results by specific geographic regions.

keyword_group_ids

Type: array[number] | Example: [1000, 2000, 3000]

Optional. Filters the request to only include data for keywords belonging to these specific keyword group IDs.

keyword_group_breakdown

Type: boolean | Example: true

Optional. If set to true, the response will provide data broken down by keyword group.

result_types

Type: array[string] | Example: ["AIO_REFERENCE_RESULT", "STANDARD_LINK"]

Optional. Filters results to include only specific SERP result types, such as standard links or AI Overviews (AIO).

includeMsv

Type: boolean | Example: true

Optional. When set to true, the response will include search volume metrics (MSV), CPC, and competition data.

limit

Type: integer | Example: 100

Optional. The maximum number of records to return in a single response.

Example Request Body

{
  "account_id": "13540",
  "start_date": "2026-01-25",
  "end_date": "2026-01-26",
  "collection_frequency": "DAILY",
  "web_property_ids": [
    12345,
    78901
  ],
  "search_engine_names": [
    "GOOGLE_en_US"
  ],
  "devices": [
    "DESKTOP",
    "SMARTPHONE"
  ],
  "locodes": [
    "US",
    "DE"
  ],
  "keyword_group_ids": [
    1000,
    2000,
    3000
  ],
  "keyword_group_breakdown": true,
  "result_types": [
    "AIO_REFERENCE_RESULT",
    "STANDARD_LINK"
  ],
  "includeMsv": true,
  "limit": 100
}

Response Schema

account_id

Type: integer | Example: 12345

The unique identifier in Conductor for the platform account associated with the data.

account_name

Type: string | Example: "Grand Budapest Hotel"

The name of the Conductor account associated with the result.

organization_id

Type: string | Example: "ABCDEGFH12345"

The unique identifier for the parent organization in Conductor.

organization_name

Type: string | Example: "Grand Budapest Hotel"

The name of the parent organization.

web_property_id

Type: integer | Example: 56789

The unique identifier for the specific tracked website or property.

web_property_name

Type: string | Example: "gbh.com"

The name of the tracked web property.

time_period_start

Type: date | Example: "2025-11-02"

The initial date (inclusive) of the reporting period.

time_period_end

Type: date | Example: "2025-11-08"

The final date (inclusive) of the reporting period.

collection_date

Type: date | Example: "2025-11-08"

The date on which data was collected for the keyword.

search_engine_name

Type: string | Example: “GOOGLE_en_US”

The search engine identifier (e.g., GOOGLE_en_US) associated with the result.

search_engine

Type: string | Example: “GOOGLE”

The search engine used for the collection.

search_engine_country_code

Type: string | Example: "US"

The country code of the search engine used for the collection.

search_engine_language_code

Type: string | Example: "en"

The language code of the search engine used for the collection.

locode

Type: string | Example: "US"

The geographic location code where the search was initiated.

device

Type: string (enum) | Example: "SMARTPHONE"

The device type used to generate the search results. 
Enum values: DESKTOP, SMARTPHONE, TABLET.

query

Type: string | Example: "spa"

The original search query or keyword associated with the result.

title

Type: string | Example: "Top 10 Hong Kong Spa & massages 2025"

The title of the search result, citation, or AI response summary.

normalized_url

Type: string | Example: "https://www.example.com/en-HK/..."

The URL of the search result, normalized to ensure consistent reporting across different tracking instances.

root_domain

Type: string | Example: "example.com"

The root domain of the result URL.

subdomain

Type: string | Example: "www.example.com"

The subdomain associated with the result URL.

result_type

Type: string (enum) | Example: "STANDARD_LINK"

The classification of the search result type. 
Enum values: STANDARD_LINK, AIO_REFERENCE_RESULT, GOOGLE_ANSWER_BOX, IMAGE_RESULT, VIDEO_RESULT, NEWS_RESULT, PLACES_GROUP, PAA_RESULT.

rank_standard

Type: integer | Example: 3

The standard rank position, which only includes traditional "blue link" results and excludes universal search elements.

rank_true

Type: integer | Example: 6

The "True Rank" position, accounting for all elements on the SERP, including universal results and AI overviews.

rank_result_type

Type: integer | Example: 3

The rank position of the result within its specific result type (e.g., the 3rd image in an image pack).

keyword_group_ids

Type: string | Example: "[1394476, 1394513]"

A list of unique identifiers for the keyword groups to which the query belongs.

keyword_group_names

Type: string | Example: "Branded, High Volume"

A list of names for the keyword groups associated with the query.

average_search_volume

Type: integer | Example: 12000

The average monthly search volume for the keyword, based on an average of the last 12 months of data.

cpc

Type: number (float) | Example: 1.25

The estimated Cost Per Click (CPC) for the query in the local currency.

competition

Type: number (float) | Example: 0.75

The competitive density for the query in paid search, represented as a value between 0 and 1.

approximate_search_volume

Type: integer | Example: 12000

The actual, approximate search volume for the keyword.

msv_month

Type: date | Example: "YYYY-MM"

The month to which monthly search volume data is related.

200 - Query completed successfully (returned when polling with queryExecutionId)

Example

{
  "results": [
    [
      "123",
      "Example Account",
      "DF3DAF2955754F543210CF505AE4761E",
      "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"
    ]
  ],
  "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": "date"
    }    
  ],
  "executionState": "COMPLETED",
  "executionId": "ath:abc123",
  "requestId": "req-123",
  "nextPageId": "87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr=="
}

202 - Query accepted and is being processed asynchronously

Example

{
  "executionState": "IN_PROGRESS",
  "executionId": "string",
  "requestId": "string"
}

400 - Invalid request parameters

Example

{
  "error": "string",
  "code": "string",
  "details": {}
}
401 - Unauthorized - Missing or invalid authentication
403 - Forbidden - Insufficient permissions
500 - Internal server error

Get Highest Ranking Page Data for Tracked Keywords

/data-api/v1/async/highest_ranking_url_per_keyword

Identifies the single highest-ranking URL for every tracked keyword within the specified time period. This is vital for enterprise teams to ensure the correct landing pages are capturing traffic and to identify internal keyword cannibalization.

Request Parameters

  • For initial requests: Include parameters from the list below.
  • For asynchronous polling: Include executionId and optional pagination parameters
    (pageSize, nextPageId).

account_id

Type: string | Example: "13540"

Required. The unique identifier(s) for the Conductor account(s) you are requesting data for.

start_date

Type: string (YYYY-MM-DD) | Example: "2026-01-25"

Required. The start date for the reporting period in YYYY-MM-DD format.

end_date

Type: string (YYYY-MM-DD) | Example: "2026-01-26"

Required. The end date for the reporting period in YYYY-MM-DD format.

collection_frequency

Type: string (enum) | Example: "DAILY"

Optional. The frequency at which rank data is collected. Supported values typically include DAILY or WEEKLY.

web_property_ids

Type: array[number] | Example: [12345, 78901]

Optional. An array of unique identifiers for the web properties to include in the request.

search_engine_names

Type: array[string] | Example: ["GOOGLE_en_US"]

Optional. An array of search engine identifiers (e.g., GOOGLE_en_US) to filter the results.

devices

Type: array[string] | Example: ["DESKTOP", "SMARTPHONE"]

Optional. Filters the results by specific device types. Supported values include DESKTOP, SMARTPHONE, and TABLET.

locodes

Type: array[string] | Example: ["US", "DE"]

Optional. An array of location codes used to filter results by specific geographic regions.

keyword_group_ids

Type: array[number] | Example: [1000, 2000, 3000]

Optional. Filters the request to only include data for keywords belonging to these specific keyword group IDs.

keyword_group_breakdown

Type: boolean | Example: true

Optional. If set to true, the response will provide data broken down by keyword group.

result_types

Type: array[string] | Example: ["AIO_REFERENCE_RESULT", "STANDARD_LINK"]

Optional. Filters results to include only specific SERP result types, such as standard links or AI Overviews (AIO).

includeMsv

Type: boolean | Example: true

Optional. When set to true, the response will include search volume metrics (MSV), CPC, and competition data.

limit

Type: integer | Example: 100

Optional. The maximum number of records to return in a single response.

Example Request Body

{
  "account_id": "13540",
  "start_date": "2026-01-25",
  "end_date": "2026-01-26",
  "collection_frequency": "DAILY",
  "web_property_ids": [
    12345,
    78901
  ],
  "search_engine_names": [
    "GOOGLE_en_US"
  ],
  "devices": [
    "DESKTOP",
    "SMARTPHONE"
  ],
  "locodes": [
    "US",
    "DE"
  ],
  "keyword_group_ids": [
    1000,
    2000,
    3000
  ],
  "keyword_group_breakdown": true,
  "result_types": [
    "AIO_REFERENCE_RESULT",
    "STANDARD_LINK"
  ],
  "includeMsv": true,
  "limit": 100
}

Response Schema

account_id

Type: integer | Example: 12345

The unique identifier in Conductor for the platform account associated with the data.

account_name

Type: string | Example: "Grand Budapest Hotel"

The name of the Conductor account associated with the result.

organization_id

Type: string | Example: "ABCDEGFH12345"

The unique identifier for the parent organization in Conductor.

organization_name

Type: string | Example: "Grand Budapest Hotel"

The name of the parent organization.

web_property_id

Type: integer | Example: 56789

The unique identifier for the specific tracked website or property.

web_property_name

Type: string | Example: "gbh.com"

The name of the tracked web property.

time_period_start

Type: date | Example: "2025-11-02"

The initial date (inclusive) of the reporting period.

time_period_end

Type: date | Example: "2025-11-08"

The final date (inclusive) of the reporting period.

collection_date

Type: date | Example: "2025-11-08"

The date on which data was collected for the keyword.

search_engine_name

Type: string | Example: “GOOGLE_en_US”

The search engine identifier (e.g., GOOGLE_en_US) associated with the result.

search_engine

Type: string | Example: “GOOGLE”

The search engine used for the collection.

search_engine_country_code

Type: string | Example: "US"

The country code of the search engine used for the collection.

search_engine_language_code

Type: string | Example: "en"

The language code of the search engine used for the collection.

locode

Type: string | Example: "US"

The geographic location code where the search was initiated.

device

Type: string (enum) | Example: "SMARTPHONE"

The device type used to generate the search results. 
Enum values: DESKTOP, SMARTPHONE, TABLET.

query

Type: string | Example: "spa"

The original search query or keyword associated with the result.

title

Type: string | Example: "Top 10 Hong Kong Spa & massages 2025"

The title of the search result, citation, or AI response summary.

normalized_url

Type: string | Example: "https://www.example.com/en-HK/..."

The URL of the search result, normalized to ensure consistent reporting across different tracking instances.

root_domain

Type: string | Example: "example.com"

The root domain of the result URL.

subdomain

Type: string | Example: "www.example.com"

The subdomain associated with the result URL.

result_type

Type: string (enum) | Example: "STANDARD_LINK"

The classification of the search result type. 
Enum values: STANDARD_LINK, AIO_REFERENCE_RESULT, GOOGLE_ANSWER_BOX, IMAGE_RESULT, VIDEO_RESULT, NEWS_RESULT, PLACES_GROUP, PAA_RESULT.

rank_standard

Type: integer | Example: 3

The standard rank position, which only includes traditional "blue link" results and excludes universal search elements.

rank_true

Type: integer | Example: 6

The "True Rank" position, accounting for all elements on the SERP, including universal results and AI overviews.

rank_result_type

Type: integer | Example: 3

The rank position of the result within its specific result type (e.g., the 3rd image in an image pack).

keyword_group_ids

Type: string | Example: "[1394476, 1394513]"

A list of unique identifiers for the keyword groups to which the query belongs.

keyword_group_names

Type: string | Example: "Branded, High Volume"

A list of names for the keyword groups associated with the query.

average_search_volume

Type: integer | Example: 12000

The average monthly search volume for the keyword, based on an average of the last 12 months of data.

cpc

Type: number (float) | Example: 1.25

The estimated Cost Per Click (CPC) for the query in the local currency.

competition

Type: number (float) | Example: 0.75

The competitive density for the query in paid search, represented as a value between 0 and 1.

approximate_search_volume

Type: integer | Example: 12000

The actual, approximate search volume for the keyword.

msv_month

Type: date | Example: "YYYY-MM"

The month to which monthly search volume data is related.

200 - Query completed successfully (returned when polling with queryExecutionId)

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": "date"
    }
  ],
  "executionState": "COMPLETED",
  "executionId": "ath:abc123",
  "requestId": "req-123",
  "nextPageId": "87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr=="
}

202- Query accepted and is being processed asynchronously

Example

{
  "executionState": "IN_PROGRESS",
  "executionId": "string",
  "requestId": "string"
}

400 - Invalid request parameters

Example

{
  "error": "string",
  "code": "string",
  "details": {}
}
401 - Unauthorized - Missing or invalid authentication
403 - Forbidden - Insufficient permissions
500 - Internal server error

Get AI Search Data about Brands

/data-api/v1/async/ai_search_brands

Extracts brand and product mentions from AI search engine responses (e.g., ChatGPT, Gemini). This allows marketing teams to quantify their "Share of Model" and understand how often they are recommended by AI compared to competitors.

Request Parameters

  • For initial requests: Include parameters from the list below.
  • For asynchronous polling: Include executionId and optional pagination parameters
    (pageSize, nextPageId).

account_id

Type: string | Example: "101"

Required. The unique identifier(s) for the Conductor account(s) you are requesting AI Search data for.

start_date

Type: string (YYYY-MM-DD) | Example: "2025-11-02"

Required. The start date for the AI search reporting period.

end_date

Type: string (YYYY-MM-DD) | Example: "2025-11-29"

Required. The end date for the AI search reporting period.

collection_frequency

Type: string (enum) | Example: "WEEKLY"

Optional. The frequency of data collection. Supported values include DAILY and WEEKLY.

web_property_ids

Type: array[number] | Example: [122556, 987654]

Optional. An array of unique identifiers for the web properties to be included in the request.

ai_search_engines

Type: array[string] | Example: ["chatgptsearch", "perplexity"]

Optional. Filters the results to specific AI engines. Supported values typically include chatgpt, perplexity, googlegemini, and mscopilot.

locodes

Type: array[string] | Example: ["US", "CA", "US NYC", "US-TX"]

Optional. Limits the results to specific location codes representing where the AI search prompts were initiated.

topics

Type: array[string] | Example: ["marketing automation", "website optimization"]

Optional. Filters the request to specific high-level topics or categories.

prompts

Type: array[string] | Example: ["best crm", "top crm"]

Optional. Filters the response to specific text prompts entered into AI search engines.

prompt_type

Type: string | Example: "branded"

Optional. Filters based on whether the prompt is classified as branded or unbranded.

intents

Type: array[string] | Example: ["Education", "Purchase"]

Optional. Filters the AI search data by detected search intent categories.

personas

Type: array[string] | Example: ["young adults", "developers"]

Optional. Filters results by the specific user personas associated with the search prompts.

brand_or_product_names

Type: array[string] | Example: ["Conductor", "Conductor AI"]

Optional. Filters based on specific brands or product names mentioned in AI responses.

brand_or_product_attributions

Type: array[string] | Example: ["You", "Partner", "SEO Competitor", "Other"]

Optional. Filters results by the attribution type of the brand or product mentioned.

Example Request Body

{
  "account_id": "101",
  "start_date": "2025-11-02",
  "end_date": "2025-11-29",
  "collection_frequency": "WEEKLY",
  "web_property_ids": [
    122556, 
    987654
  ],
  "ai_search_engines": [
    "chatgptsearch", 
    "perplexity"
  ],
  "locodes": [
    "US", 
    "CA", 
    "US NYC", 
    "US-TX"
  ],
  "topics": [
    "marketing automation", 
    "website optimization"
  ],
  "prompts": [
    "best crm", 
    "top crm"
  ],
  "prompt_type": "branded",
  "intents": [
    "Education", 
    “Purchase”
  ],
  "personas": [
    "young adults", 
    "developers"
  ],
  "brand_or_product_names": [
    "Conductor", 
    "Conductor AI"
  ],
  "brand_or_product_attributions": [
    "You", 
    "Partner", 
    "SEO Competitor", 
    "Other"
    ]
}

Response Schema

organization_id

Type: string | Example: "ABCDEGFH12345"

The unique identifier for the parent organization in Conductor.

organization_name

Type: string | Example: "Grand Budapest Hotel"

The name of the parent organization.

account_id

Type: integer | Example: 12345

The unique identifier in Conductor for the platform account associated with the data.

account_name

Type: string | Example: "Grand Budapest Hotel"

The name of the Conductor account associated with the result.

web_property_id

Type: integer | Example: 56789

The unique identifier for the specific tracked website or property.

web_property_name

Type: string | Example: "gbh.com"

The name of the tracked web property.

time_period_start

Type: date | Example: "2025-11-02"

The initial date (inclusive) of the reporting period.

time_period_end

Type: date | Example: "2025-11-08"

The final date (inclusive) of the reporting period.

collection_frequency

Type: string (enum) | Example: "WEEKLY"

The frequency at which the data is tracked and updated in the platform. 
Enum values: DAILY, WEEKLY.

locode

Type: string | Example: "US"

The geographic location code where the search was initiated.

language

Type: string | Example: "en_US"

The language setting used for the search or AI prompt.

ai_search_engine

Type: string (enum) | Example: "chatgpt"

The specific AI search platform where the data was collected. 
Enum values: perplexity, googlegemini, googleaio, googleaimode, chatgpt, chatgptsearch, mscopilot.

topic

Type: string | Example: "bali honeymoon escapes"

The broad thematic category to which the tracked prompt belongs.

prompt

Type: string | Example: "aman resorts bali honeymoon"

The exact question or command entered into the AI search engine.

prompt_type

Type: string (enum) | Example: "branded"

Indicates whether the generated prompt is classified as branded or unbranded. 
Enum values: branded, unbranded.

intent

Type: string (enum) | Example: "Education"

The detected purpose behind the user's search prompt as classified by Conductor's AI. 
Enum values: Brand/Service Navigation, Comparison, Education, Pricing, Purchase, Recommendations, Support, Other.

persona

Type: string | Example: "Marketing Manager"

The specific user persona assigned to the prompt to guide the AI search context.

brand_or_product_name

Type: string | Example: "Adidas"

The name of the brand or product identified within the AI-generated response.

brand_or_product_entity_type

Type: string | Example: "brand"

Identifies whether the entity extracted from the AI response is a brand or a specific product.

brand_or_product_attribution

Type: string (enum) | Example: "competitor"

Classification of the brand or product mentioned in the AI response relative to your organization. 
Enum values: you, competitor, other.

ai_response_collected

Type: boolean | Example: true

Indicates whether an AI response was successfully retrieved from the engine for the given prompt during the collection period.

web_search_triggered

Type: boolean | Example: false

Indicates whether the AI search engine triggered a live web crawl or search to formulate the response.

200 - Query completed successfully (returned when polling with queryExecutionId)

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=="
}

202 - Query accepted and is being processed asynchronously

Example

{
  "executionState": "IN_PROGRESS",
  "executionId": "string",
  "requestId": "string"
}

400 - Invalid request parameters

Example

	
Invalid request parameters

Media type

application/json
Example Value
Schema
{
  "error": "string",
  "code": "string",
  "details": {}
}
401 - Unauthorized - API key missing or invalid
403 - Forbidden - Insufficient permissions
429 - Too many requests
500 - Internal server error

Get AI Search Data about Citations

/data-api/v1/async/ai_search_citations

Provides data on the specific URLs cited by AI search engines as sources. Understanding which pages are being used as "authority sources" helps teams optimize content for better AI citation rates and referral traffic.

Request Parameters

  • For initial requests: Include parameters from the list below.
  • For asynchronous polling: Include executionId and optional pagination parameters
    (pageSize, nextPageId).

account_id

Type: string | Example: "101"

Required. The unique identifier(s) for the Conductor account(s) you are requesting AI Search data for.

start_date

Type: string (YYYY-MM-DD) | Example: "2025-11-02"

Required. The start date for the AI search reporting period.

end_date

Type: string (YYYY-MM-DD) | Example: "2025-11-29"

Required. The end date for the AI search reporting period.

collection_frequency

Type: string (enum) | Example: "WEEKLY"

Optional. The frequency of the data collection. Supported values include DAILY and WEEKLY.

web_property_ids

Type: array[number] | Example: [122556, 987654]

Optional. An array of unique identifiers for the web properties to be included in the request.

ai_search_engines

Type: array[string] | Example: ["chatgptsearch", "perplexity"]

Optional. Filters the results to specific AI engines. Supported values typically include chatgpt, perplexity, googlegemini, and mscopilot.

locodes

Type: array[string] | Example: ["US", "CA", "US NYC"]

Optional. Limits the results to specific location codes representing where the AI search prompts were initiated.

languages

Type: array[string] | Example: ["en_US", "hant_TW"]

Optional. Filters the response based on the language settings used for the AI prompts.

topics

Type: array[string] | Example: ["marketing automation", "website optimization"]

Optional. Filters the request to specific high-level topics or categories.

prompts

Type: array[string] | Example: ["best crm", "top crm"]

Optional. Filters the response to specific text prompts entered into AI search engines.

prompt_type

Type: string | Example: "branded"

Optional. Filters based on whether the prompt is classified as branded or unbranded.

intents

Type: array[string] | Example: ["Education", "Purchase"]

Optional. Filters the AI search data by the detected search intent (e.g., Commercial, Informational).

personas

Type: array[string] | Example: ["young adults", "developers"]

Optional. Filters results by the specific user personas associated with the search prompts.

root_domains

Type: array[string] | Example: ["conductor.com", "abc.com"]

Optional. Filters results by the root domains mentioned or cited in the AI responses.

domains

Type: array[string] | Example: ["blog.conductor.com", "about.conductor.com"]

Optional. Filters results by specific subdomains mentioned in the AI responses.

citation_urls

Type: array[string] | Example: ["https://www.conductor.com/blog/..."]

Optional. Filters the response to include citations for specific source URLs.

citation_attributions

Type: array[string] | Example: ["You", "Partner", "SEO Competitor"]

Optional. Filters based on the ownership of the cited sources (e.g., You, Competitor, Other).

Example Request Body

{
  "account_id": "101",
  "start_date": "2025-11-02",
  "end_date": "2025-11-29",
  "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”
  ],
  "root_domains": [
    "conductor.com",
    “abc.com”
  ],
  "domains": [
    "blog.conductor.com",
    “about.conductor.com”
  ],
  "citation_urls": [
    “https://www.conductor.com/blog/...”
  ],
  "citation_attributions": [
    "You",
    "Partner",
    “SEO Competitor”
  ]
}

Response Schema

organization_id

Type: string | Example: "ABCDEGFH12345"

The unique identifier for the parent organization in Conductor.

organization_name

Type: string | Example: "Grand Budapest Hotel"

The name of the parent organization.

account_id

Type: integer | Example: 12345

The unique identifier in Conductor for the platform account associated with the data.

account_name

Type: string | Example: "Grand Budapest Hotel"

The name of the Conductor account associated with the result.

web_property_id

Type: integer | Example: 56789

The unique identifier for the specific tracked website or property.

web_property_name

Type: string | Example: "gbh.com"

The name of the tracked web property.

time_period_start

Type: date | Example: "2025-11-02"

The initial date (inclusive) of the reporting period.

time_period_end

Type: date | Example: "2025-11-08"

The final date (inclusive) of the reporting period.

collection_frequency

Type: string (enum) | Example: "WEEKLY"

The frequency at which the data is tracked and updated in the platform. 
Enum values: DAILY, WEEKLY.

locode

Type: string | Example: "US"

The geographic location code where the search was initiated.

language

Type: string | Example: "en_US"

The language setting used for the search or AI prompt.

ai_search_engine

Type: string (enum) | Example: "chatgpt"

The specific AI search platform where the data was collected. 
Enum values: perplexity, googlegemini, googleaio, googleaimode, chatgpt, chatgptsearch, mscopilot.

topic

Type: string | Example: "bali honeymoon escapes"

The broad thematic category to which the tracked prompt belongs.

prompt

Type: string | Example: "aman resorts bali honeymoon"

The exact question or command entered into the AI search engine.

prompt_type

Type: string (enum) | Example: "branded"

Indicates whether the generated prompt is classified as branded or unbranded. 
Enum values: branded, unbranded.

intent

Type: string (enum) | Example: "Education"

The detected purpose behind the user's search prompt as classified by Conductor's AI. 
Enum values: Brand/Service Navigation, Comparison, Education, Pricing, Purchase, Recommendations, Support, Other.

persona

Type: string | Example: "Marketing Manager"

The specific user persona assigned to the prompt to guide the AI search context.

citation_title

Type: string | Example: "The Ultimate Guide to SEO"

The title of the webpage that was cited as a source in the AI response.

citation_url

Type: string | Example: "https://www.conductor.com/blog/seo-guide"

The specific URL referenced by the AI engine to generate its response.

citation_domain

Type: string | Example: "conductor.com"

The root domain of the source cited by the AI search engine.

citation_web_property_segment

Type: string | Example: "conductor.com"

The web property segment classification for the cited source.

citation_attribution

Type: string (enum) | Example: "YOU"

The attribution category of the cited URL. 
Enum values: YOU, COMPETITOR, OTHER.

ai_response_collected

Type: boolean | Example: true

Indicates whether an AI response was successfully retrieved from the engine for the given prompt during the collection period.

web_search_triggered

Type: boolean | Example: false

Indicates whether the AI search engine triggered a live web crawl or search to formulate the response.

200 - Query completed successfully (returned when polling with queryExecutionId) 

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 | The Leading Organic Marketing Platform",
      "https://www.conductor.com/",
      "conductor.com",
      "blog.conductor.com",
      "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": "citation_title",
      "type": "string"
    },
    {
      "name": "citation_url",
      "type": "string"
    },
    {
      "name": "citation_domain",
      "type": "string"
    },
    {
      "name": "citation_web_property_segment",
      "type": "string"
    },
    {
      "name": "citation_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=="
}

202 - Query accepted and is being processed asynchronously

Example

{
  "executionState": "IN_PROGRESS",
  "executionId": "string",
  "requestId": "string"
}

400 - Invalid request parameters

Example

{
  "error": "string",
  "code": "string",
  "details": {}
}
401 - Unauthorized - API key missing or invalid
403 - Forbidden - Insufficient permissions
429 - Too many requests
500 - Internal server error

Get AI Search Data about Sentiment

/data-api/v1/async/ai_search_sentiments

Extracts the sentiment (Positive, Negative, Neutral) and specific descriptive snippets associated with your brand in AI responses. This is critical for Reputation Management and understanding the "opinion" AI models have of your products.

Request Parameters

  • For initial requests: Include parameters from the list below.
  • For asynchronous polling: Include executionId and optional pagination parameters
    (pageSize, nextPageId).

account_id

Type: string | Example: "101"

Required. The unique identifier(s) for the Conductor account(s) you are requesting AI search sentiment data for.

start_date

Type: string (YYYY-MM-DD) | Example: "2024-03-01"

Required. The start date for the reporting period in YYYY-MM-DD format.

end_date

Type: string (YYYY-MM-DD) | Example: "2024-03-15"

Required. The end date for the reporting period in YYYY-MM-DD format.

collection_frequency

Type: string (enum) | Example: "WEEKLY"

Optional. The frequency at which the sentiment data was collected.

limit

Type: integer | Example: 10000

Optional. The maximum number of sentiment records to return in the response.

web_property_ids

Type: array[number] | Example: [122556, 987654]

Optional. An array of unique identifiers for the web properties to include in the request.

ai_search_engines

Type: array[string] | Example: ["chatgptsearch"]

Optional. Filters results to specific AI search engines.

locodes

Type: array[string] | Example: ["US", "CA", "US NYC", "US-TX"]

Optional. Limits results to specific location codes representing where the AI search prompt was initiated.

topics

Type: array[string] | Example: ["marketing automation", "website optimization"]

Optional. Filters the response to specific high-level topics or categories.

prompts

Type: array[string] | Example: ["best crm", "top crm"]

Optional. Filters the response to specific text prompts entered into AI search engines.

prompt_type

Type: string | Example: "branded"

Optional. Filters based on whether the search prompt is classified as branded or unbranded.

intents

Type: array[string] | Example: ["Education", "Purchase"]

Optional. Filters AI search results by detected user intent categories.

personas

Type: array[string] | Example: ["young adults", "developers"]

Optional. Filters results by specific user personas associated with the search prompts.

sentiment_brands

Type: array[string] | Example: ["Conductor", "Conductor AI"]

Optional. Filters based on the specific brands for which sentiment was extracted.

sentiment_values

Type: array[string] | Example: ["positive"]

Optional. Filters results by specific sentiment values (e.g., positive, negative, neutral).

sentiment_categories

Type: array[string] | Example: ["pricing"]

Optional. Filters by the category of the detected sentiment.

sentiment_source_domains

Type: array[string] | Example: ["example.com"]

Optional. Filters results by the source domains that provided the sentiment data.

Example Request Body

{
  "account_id": "101",
  "start_date": "2024-03-01",
  "end_date": "2024-03-15",
  "collection_frequency": "WEEKLY",
  "limit": 10000,
  "web_property_ids": [
    122556,
    987654
  ],
  "ai_search_engines": [
    "chatgptsearch"
  ],
  "locodes": [
    "US",
    "CA",
    "US NYC",
    "US-TX"
  ],
  "topics": [
    "marketing automation",
    "website optimization"
  ],
  "prompts": [
    "best crm",
    "top crm"
  ],
  "prompt_type": "branded",
  "intents": [
    "Education",
    "Purchase"
  ],
  "personas": [
    "young adults",
    "developers"
  ],
  "sentiment_brands": [
    "Conductor",
    “Conductor AI”
  ],
  "sentiment_values": [
    "positive"
  ],
  "sentiment_categories": [
    "pricing"
  ],
  "sentiment_source_domains": [
    "example.com"
  ]
}

Response Schema

organization_id

Type: string | Example: "ABCDEGFH12345"

The unique identifier for the parent organization in Conductor.

organization_name

Type: string | Example: "Grand Budapest Hotel"

The name of the parent organization.

account_id

Type: integer | Example: 12345

The unique identifier in Conductor for the platform account associated with the data.

account_name

Type: string | Example: "Grand Budapest Hotel"

The name of the Conductor account associated with the result.

web_property_id

Type: integer | Example: 56789

The unique identifier for the specific tracked website or property.

web_property_name

Type: string | Example: "gbh.com"

The name of the tracked web property.

time_period_start

Type: date | Example: "2025-11-02"

The initial date (inclusive) of the reporting period.

time_period_end

Type: date | Example: "2025-11-08"

The final date (inclusive) of the reporting period.

collection_frequency

Type: string (enum) | Example: "WEEKLY"

The frequency at which the data is tracked and updated in the platform. 
Enum values: DAILY, WEEKLY.

locode

Type: string | Example: "US"

The geographic location code where the search was initiated.

language

Type: string | Example: "en_US"

The language setting used for the search or AI prompt.

ai_search_engine

Type: string (enum) | Example: "chatgpt"

The specific AI search platform where the data was collected. 
Enum values: perplexity, googlegemini, googleaio, googleaimode, chatgpt, chatgptsearch, mscopilot.

topic

Type: string | Example: "bali honeymoon escapes"

The broad thematic category to which the tracked prompt belongs.

prompt

Type: string | Example: "aman resorts bali honeymoon"

The exact question or command entered into the AI search engine.

prompt_type

Type: string (enum) | Example: "branded"

Indicates whether the generated prompt is classified as branded or unbranded. 
Enum values: branded, unbranded.

intent

Type: string (enum) | Example: "Education"

The detected purpose behind the user's search prompt as classified by Conductor's AI. 
Enum values: Brand/Service Navigation, Comparison, Education, Pricing, Purchase, Recommendations, Support, Other.

persona

Type: string | Example: "Marketing Manager"

The specific user persona assigned to the prompt to guide the AI search context.

sentiment_brand

Type: string | Example: "Nike"

The specific brand mentioned in the AI response for which sentiment was analyzed.

sentiment_value

Type: string (enum) | Example: "positive"

The polarity of the detected sentiment. 
Enum values: positive, negative, neutral.

sentiment_score

Type: integer | Example: 8

A numeric score representing the strength of the sentiment, typically on a scale of 1 to 10.

sentiment_category

Type: string (enum) | Example: "Quality"

The category of the detected sentiment. 
Enum values: Health, Quality, Price, User-friendliness, Popularity, Ethics, Service, Experience, Misc.

sentiment_snippet

Type: string | Example: "Offers intuitive tools that simplify SEO."

The specific raw text segment from the AI response used to derive the sentiment.

sentiment_source_url

Type: string | Example: "https://reddit.com/r/seo/..."

The specific URL cited by the AI search engine that provided the context for the sentiment.

sentiment_source_domain

Type: string | Example: "techradar.com"

The root domain of the source used by the AI to form the sentiment-based response.

ai_response_collected

Type: boolean | Example: true

Indicates whether an AI response was successfully retrieved from the engine for the given prompt during the collection period.

web_search_triggered

Type: boolean | Example: false

Indicates whether the AI search engine triggered a live web crawl or search to formulate the response.

200 - Query completed successfully (returned when polling with queryExecutionId)

Example

{
  "results": [
    [
      "Example Organization",
      "DF3DAF2955754FDDB180CF505AE4761E",
      "Example Account",
      "123",
      "conductor.com",
      "456",
      "2024-03-01",
      "2024-03-15",
      "WEEKLY",
      "US-NYC",
      "en_US",
      "chatgptsearch",
      "marketing automation",
      "best marketing automation tools",
      "branded",
      "commercial",
      "Marketing Manager",
      "Conductor",
      "positive",
      "10",
      "pricing",
      "Conductor offers intuitive tools that simplify SEO workflows.",
      "https://example.com/review",
      "example.com",
      "true",
      "false"
    ]
  ],
  "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": "sentiment_brand",
      "type": "string"
    },
    {
      "name": "sentiment_value",
      "type": "string"
    },
    {
      "name": "sentiment_score",
      "type": "float"
    },
    {
      "name": "sentiment_category",
      "type": "string"
    },
    {
      "name": "sentiment_snippet",
      "type": "string"
    },
    {
      "name": "sentiment_source_url",
      "type": "string"
    },
    {
      "name": "sentiment_source_domain",
      "type": "string"
    },
    {
      "name": "ai_response_collected",
      "type": "boolean"
    },
    {
      "name": "web_search_triggered",
      "type": "boolean"
    }
  ],
  "executionState": "COMPLETED",
  "executionId": "ath:abc123",
  "requestId": "req-123"
}

202 - Query accepted and is being processed asynchronously

Example

{
  "executionState": "IN_PROGRESS",
  "executionId": "string",
  "requestId": "string"
}

400 - Invalid request parameters

Example

{
  "error": "string",
  "code": "string",
  "details": {}
}
401 - Unauthorized - API key missing or invalid
403 - Forbidden - Insufficient permissions
429 - Too many requests
500 - Internal server error

Reference

Endpoint-Specific Filters

Each endpoint includes request parameters that can filter data before it is sent.

Keyword-Only Filters

  • search_engine_names
    • Type: array
    • Filter to see data only for specific search engines: ["GOOGLE_en_US"]
  • devices
    • Type: array
    • ["DESKTOP", "SMARTPHONE"]
  • locodes
    • Type: array
    • ["US", "DE"]
  • keyword_group_ids
    • Type: array[number]
    • Filter to see data only for specific keyword groups: [1000, 2000, 2000]
  • result_types
    • Type: array
    • Filter to see data only for specific result types: ["AIO_REFERENCE_RESULT", “STANDARD_LINK"]

Brand-Only Filters

  • brand_or_product_attributions
    • Type: array
    • Filter by attribution: ["You"], ["SEO Competitor"], ["other"]
  • brand_or_product_names
    • Type: array
    • Filter by brand/product name: ["nike", "adidas"]

Citation-Only Filters

  • citation_attributions
    • Type: array
    • Filter by attribution: ["You"], ["other"]
       
  • root_domains
    • Type: array
    • Filter by root domain: ["example.com"]
       
  • domains
    • Type: array
    • Filter by subdomain: ["www.example.com"]
  • citation_urls
    • Type: array
    • Filter by specific URLs

Sentiment-Only Filters

  • sentiment_values
    • Type: array
    • Filter by sentiment value: ["positive"], ["negative"], ["neutral"]
  • sentiment_brands
    • Type: array
    • Filter sentiment for specific brands
  • sentiment_categories
    • Type: array
    • Filter by sentiment category: ["experience", "pricing", "support"]
  • sentiment_source_domains
    • Type: array
    • Filter by source domain: ["wikipedia.org"]

Response Format

All endpoints return data in the same structure—an array of arrays with a separate schema definition. This is more compact than an array of objects.

{
  "results": [
    ["Example Co", "D7F290...", "Example Co", "13540", ...],
    ["Example Co", "D7F290...", "Example Co", "13540", ...],
    ...
  ],
  "schema": [
    {"name": "organization_name", "type": "string"},
    {"name": "organization_id", "type": "string"},
    ...
  ],
  "executionState": null,        // null = complete, "IN_PROGRESS" = still running
  "executionId": "enga:...",
  "requestId": "...",
  "nextPageId": "..."           // non-null if more pages available
}

Parsing Results into Rows

field_names = [f["name"] for f in data["schema"]]
rows = [dict(zip(field_names, row)) for row in data["results"]]

# Now each row is a dict: {"organization_name": "Example Co", "account_id": "13540", ...}

Tips and Best Practices

Authentication

  • Generate a fresh signature for every request, including poll requests—the timestamp-based signature expires quickly.
  • The x-api-gateway-key header is required and use the API key value.
  • The apiKey and sig go as query parameters in the URL, not in the body.

Request Format

  • All endpoints use POST with a JSON body.
  • Array filters (topics, engines, etc.) must be JSON arrays even for single values: ["chatgpt"] not "chatgpt".
  • prompt_type and collection_frequency are strings, not arrays.

Async Handling

  • Expect 15-60 seconds for results depending on query complexity.
  • Poll every 3-5 seconds—no need to hammer the API!
  • Set a maximum poll limit (e.g. 20 attempts) to avoid infinite loops.
  • Check executionState: "IN_PROGRESS" means keep polling, null means data is ready.

Performance

  • Use filters to narrow results. Unfiltered queries can return very large datasets.
  • The default limit appears to be 999 rows per page. Use nextPageId for pagination.
  • Narrow date ranges and specific topics yield faster responses.
  • The "all filters combined" approach may return 0 rows if the combination is too specific.

Common Gotchas

  • Missing x-api-gateway-key returns HTTP 500, not 401.
  • The domains filter (citations) expects subdomains like www.examples.com; use root_domains for example.com.
  • Response data uses array-of-arrays format: you must zip with the schema to get named fields.