SerpJob reference

SERP Tasks

The SerpJob object, field by field.

Google: live · not GA

Reference for the task object returned by the create endpoints and by GET /v1/serp/tasks/{task_id}: every field, its type, and which timestamp is filled at which step.

Get API key Field reference

A failed task

{"job":{"id":"<task_id>","kind":"google_images","status":"failed",
  "request":{"q":"…","country":"US","hl":"en","device":"desktop"},
  "result":null,"error":{"code":"<code>","message":"<message>","retryable":false},
  "attempt_count":3,"max_attempts":3,"created_at":"<date-time>","finished_at":"<date-time>"}}

SerpJob field table

SerpJob fields
Field	Type	Notes
id	string	The task_id you poll.
kind	enum	google_organic, google_news or google_images.
status	enum	queued, running, completed or failed.
request	SerpJobRequest	{q, country, hl, device} as accepted.
result	object, nullable	The sync-shaped response once completed; null before.
error	SerpJobError, nullable	{code, message, retryable (default false)}.
attempt_count	integer	Default 0.
max_attempts	integer	Default 3.
created_at, updated_at	date-time	Set on create; updated_at moves with each change.
started_at, finished_at	date-time, nullable	Set when running starts and when a final status is reached.

id

Type: string

Notes: The task_id you poll.

kind

Type: enum

Notes: google_organic, google_news or google_images.

status

Type: enum

Notes: queued, running, completed or failed.

request

Type: SerpJobRequest

Notes: {q, country, hl, device} as accepted.

result

Type: object, nullable

Notes: The sync-shaped response once completed; null before.

error

Type: SerpJobError, nullable

Notes: {code, message, retryable (default false)}.

attempt_count

Type: integer

Notes: Default 0.

max_attempts

Type: integer

Notes: Default 3.

created_at, updated_at

Type: date-time

Notes: Set on create; updated_at moves with each change.

started_at, finished_at

Type: date-time, nullable

Notes: Set when running starts and when a final status is reached.

Status transitions

Which timestamp is filled at each step
Transition	Timestamps filled
created → queued	created_at, updated_at
queued → running	started_at, updated_at
running → completed	finished_at, updated_at; result set
running → failed	finished_at, updated_at; error set

created → queued

Timestamps filled: created_at, updated_at

queued → running

Timestamps filled: started_at, updated_at

running → completed

Timestamps filled: finished_at, updated_at; result set

running → failed

Timestamps filled: finished_at, updated_at; error set

404 and 503 on poll

404 not_found: the task does not exist or does not belong to your Team.
503 service_unavailable: the endpoint is not enabled right now; nothing is billed.

Launch status for this page

Check engine availability before choosing an endpoint. Google also supports News, Images and asynchronous tasks.

GoogleLiveGoogle is callable today with a Bearer API key.

SERP searches are charged per successful search at a display rate of 2 Credits per search; failed searches are not charged. Polling task status is free. The current rate is on Pricing.

What this is not

error.code values are not enumerated.
No webhook.
Google only.

Frequently asked questions

What does 404 on poll mean?

not_found: the task does not exist or does not belong to your Team.

Can result be null?

Yes. It is null until the task completes.

Is retryable always set?

It defaults to false.

Max attempts?

max_attempts defaults to 3.

Build against SerpJob

Get an API key and poll your first task.

Get API key SERP API overview Read the SERP docs