Skip to main content
POST
Start a persisted keyword research 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 starting a persisted bulk keyword research job.

Attributes: research_type: One of 'bulk', 'suggestions', or 'domain_keywords'. input_params: Payload forwarded to the worker — keywords list, location_code, language_code, domain, etc.

research_type
string
required

'bulk', 'suggestions', or 'domain_keywords'

input_params
Input Params · object
required

keywords list, location_code, language_code, etc.

refresh_id
string<uuid> | null

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

Response

Successful Response

success
boolean
default:true
data
KeywordResearchJobResponse · object | null

Full response model for a KeywordResearchJob record.

Attributes: id: UUID of the job record. org_id: Organization this job belongs to. project_id: Optional project scope. status: Current lifecycle state (pending, processing, completed, failed). research_type: Type of research that was requested. input_params: Original request parameters passed to the worker. results_data: Keyword result rows once the job completes. result_count: Number of result rows returned. error_message: Error detail when status is 'failed'. completed_at: Timestamp when the job transitioned to completed/failed. created_by: UUID of the user who started the job. created_at: Record creation timestamp. updated_at: Record last-modified timestamp.