Skip to main content
POST
Start a persisted AI search job

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Key
string | null

Path Parameters

project_id
string<uuid>
required

Body

application/json

Request body for triggering a persisted AI search job.

Attributes: feature_type: Which AI search tool to run. One of: google_ai_mode, chatgpt_visibility, llm_benchmark, ai_keyword_trends, citation_gap. input_params: Tool-specific parameters. Expected keys vary by feature_type: - google_ai_mode: keyword, location_code, language_code - chatgpt_visibility: keyword, location_code, language_code - llm_benchmark: keyword, location_code, language_code - ai_keyword_trends: keywords (list), location_code, language_code - citation_gap: keywords (list), your_domain, competitor_domains (list), location_code, language_code

feature_type
string
required

AI search feature to execute. One of: google_ai_mode, chatgpt_visibility, llm_benchmark, ai_keyword_trends, citation_gap.

input_params
Input Params · object

Tool-specific parameters (keyword, keywords, location_code, language_code, your_domain, competitor_domains).

refresh_id
string<uuid> | null

If provided, resets the existing result instead of creating a new one.

Response

Successful Response

success
boolean
default:true
data
AiSearchResultResponse · object | null

Full AI search result record returned from the API.

Attributes: id: Primary key UUID. project_id: Project this result belongs to. feature_type: Which AI search feature produced this result. status: Lifecycle state — pending, processing, completed, failed. input_params: Parameters that were supplied when the job was triggered. result_data: The DataForSEO response payload (null while pending/processing). error_message: Populated when status is failed. completed_at: Timestamp when the worker finished (or errored). created_by: UUID of the user who triggered the job. created_at: Row creation timestamp. updated_at: Last modification timestamp.