Skip to main content
POST
/
data-api
/
v1
/
async
/
ai_search_response
Query AI Search Response Data (Async)
curl --request POST \
  --url 'https://api-universal.conductor.com/data-api/v1/async/ai_search_response?apiKey=&sig=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "time_period_start": "2025-11-02",
  "time_period_end": "2025-11-08",
  "account_id": 101,
  "limit": 100,
  "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 marketing automation tools",
    "website optimization tools"
  ],
  "intents": [
    "Education",
    "Purchase"
  ],
  "personas": [
    "young adults",
    "developers"
  ]
}
'
{
  "results": [
    [
      "Conductor Organization",
      "base64-encoded-organization-id",
      "Conductor Account",
      "123",
      "conductor.com",
      "456",
      "WEEKLY",
      "2026-01-11",
      "2026-01-17",
      "US",
      "en_US",
      "engine-123",
      "chatgptsearch",
      "marketing automation",
      "best AEO and GEO platforms",
      "commercial",
      "Marketing Manager",
      "Here are some of the best marketing automation tools available...",
      "2024-03-15"
    ]
  ],
  "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": "collection_frequency",
      "type": "string"
    },
    {
      "name": "time_period_start",
      "type": "date"
    },
    {
      "name": "time_period_end",
      "type": "date"
    },
    {
      "name": "locode",
      "type": "string"
    },
    {
      "name": "language",
      "type": "string"
    },
    {
      "name": "ai_search_engine_id",
      "type": "string"
    },
    {
      "name": "ai_search_engine",
      "type": "string"
    },
    {
      "name": "topic",
      "type": "string"
    },
    {
      "name": "prompt",
      "type": "string"
    },
    {
      "name": "intent",
      "type": "string"
    },
    {
      "name": "persona",
      "type": "string"
    },
    {
      "name": "ai_response",
      "type": "string"
    },
    {
      "name": "collection_date",
      "type": "date"
    }
  ],
  "executionState": "COMPLETED",
  "executionId": "enga:f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "requestId": "9e3b7c12-f4a5-48d1-b6e9-0c32d5a8e1b4",
  "nextPageId": "87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==",
  "totalRowCount": 1000
}

Authorizations

​
apiKey
string
query
required

API Key as a query parameter

​
sig
string
query
required

Request signature computed using API key and secret. Valid for 5 minutes after creation.

Body

application/json

Submit a new query with filters and parameters. Returns an executionId to track the query.

​
time_period_start
string<date>
required

Start date of the time period; if collection_frequency is WEEKLY, this field must be Sunday

Example:

"2025-11-02"

​
time_period_end
string<date>
required

End date of the time period; if collection_frequency is WEEKLY, this field must be Saturday

Example:

"2025-11-08"

​
collection_frequency
enum<string>
required

Data collection frequency

Available options:
DAILY,
WEEKLY
​
account_id
integer
required

Required account ID to filter results

Required range: x >= 1
Example:

101

​
limit
integer
default:1000

Maximum number of results to return

Required range: 0 <= x <= 1000
Example:

100

​
web_property_ids
integer[]

(Optional) comma-separated list of web property IDs to filter results. If not provided, results are not filtered by web property

Required range: x >= 1
Example:
[122556, 987654]
​
ai_search_engines
string[]

(Optional) comma-separated list of AI engines to filter

Example:
["chatgptsearch", "perplexity"]
​
locodes
string[]

(Optional) comma-separated list of locodes to filter (case-insensitive; values will be uppercased). Supports locales like country codes "DE" or city locodes "US NYC" or state codes "PL-02"

Required string length: 2 - 12
Example:
["US", "CA", "US NYC", "US-TX"]
​
languages
string[]

(Optional) comma-separated list of search engine language codes to filter (case-insensitive; values will be uppercased).

Required string length: 2 - 7
Example:
["en_US", "hant_TW"]
​
topics
string[]

(Optional) comma-separated list of topics to filter

Example:
[
  "marketing automation",
  "website optimization"
]
​
prompts
string[]

(Optional) comma-separated list of prompts to filter

Example:
[
  "best marketing automation tools",
  "website optimization tools"
]
​
intents
string[]

(Optional) comma-separated list of intents to filter

Example:
["Education", "Purchase"]
​
personas
string[]

(Optional) comma-separated list of personas to filter

Example:
["young adults", "developers"]

Response

Query completed successfully

​
results
string[][]

List of query results. Each item is a positional tuple row. Available only when executionState is COMPLETED.

Positional tuple row for AI Search Response results. Column order matches the schema metadata. All values are returned as strings.

Minimum array length: 19
​
executionState
enum<string>

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.
Available options:
IN_PROGRESS,
COMPLETED,
FAILED
​
executionId
string

Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination.

​
requestId
string

Unique identifier for the HTTP request, useful for support and debugging.

​
nextPageId
string

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
integer<int64>

Total number of rows across all pages (if available).

​
schema
object[]

Column metadata providing the name and type for each position in the results tuple.