Skip to main content
POST
/
data-api
/
v1
/
async
/
ai_search_sentiments
Query AI Search Sentiments Data (Async)
curl --request POST \
  --url 'https://api-universal.conductor.com/data-api/v1/async/ai_search_sentiments?apiKey=&sig=' \
  --header 'Content-Type: application/json' \
  --header 'X-API-GATEWAY-KEY: <api-key>' \
  --data '
{
  "account_id": 101,
  "start_date": "2024-03-01",
  "end_date": "2024-03-15",
  "collection_frequency": "WEEKLY",
  "web_property_ids": [
    122556,
    987654
  ],
  "ai_search_engines": [
    "chatgptsearch"
  ],
  "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"
  ],
  "sentiment_brands": [
    "Conductor",
    "Conductor AI"
  ],
  "sentiment_values": [
    "positive"
  ],
  "sentiment_categories": [
    "pricing"
  ],
  "sentiment_source_domains": [
    "example.com"
  ]
}
'
{
  "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",
  "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.

​
X-API-GATEWAY-KEY
string
header
required

API Key as an HTTP header (must match apiKey query parameter)

Body

application/json

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

​
account_id
integer
required

Required account ID to filter results.

Required range: x >= 1
Example:

101

​
start_date
string<date>
required

Start date of the time period (yyyy-MM-dd). If collection_frequency is WEEKLY or not set, this must be a Sunday.

Example:

"2024-03-01"

​
end_date
string<date>
required

End date of the time period (yyyy-MM-dd). If collection_frequency is WEEKLY or not set, this must be a Saturday.

Example:

"2024-03-15"

​
collection_frequency
enum<string>
default:WEEKLY

Frequency of data collection.

Available options:
DAILY,
WEEKLY
​
web_property_ids
integer[]

(Optional) list of web property IDs to filter results.

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

(Optional) list of AI engines to filter.

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

(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).

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

(Optional) list of search engine language codes to filter (case-insensitive; e.g., en_US, hant_TW).

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

(Optional) list of topics to filter.

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

(Optional) list of prompts to filter.

Example:
["best crm", "top crm"]
​
prompt_type
enum<string>

(Optional) indicates whether the prompt is branded or unbranded.

Available options:
branded,
unbranded
Example:

"branded"

​
intents
string[]

(Optional) list of intents to filter. Options include: Education, Brand/Service Navigation, Pricing, Support, Recommendations, Comparison, Purchase, Other.

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

(Optional) list of user-defined personas to filter (e.g., "android user", "developers").

Example:
["young adults", "developers"]
​
sentiment_brands
string[]

(Optional) list of sentiment brands to filter (case-insensitive).

Example:
["Conductor", "Conductor AI"]
​
sentiment_values
enum<string>[]

(Optional) list of sentiment values to filter.

Available options:
positive,
neutral,
negative
Example:
["positive"]
​
sentiment_categories
string[]

(Optional) list of sentiment categories to filter.

Example:
["pricing"]
​
sentiment_source_domains
string[]

(Optional) list of sentiment source domains to filter.

Example:
["example.com"]

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 sentiments results. Column order matches the schema metadata. All values are returned as strings.

Required array length: 26 elements
​
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.