Get a task

GET

/serp/tasks/{id}

curl --request GET \
  --url https://api.seo-checker.com.ua/v1/serp/tasks/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

• Production
• Development

Retrieve one task by id. Poll this endpoint after submitting — it returns the current status; result is populated once status is done, and error once status is error.

Authorizations

• apiKey

Parameters

Path Parameters

id

required

string format: uuid

Responses

200

The task.

Media typeapplication/json

object

task_id

string format: uuid

type

string

Allowed values: serp_full

status

Lifecycle: queued → running → done | error. A cache hit is created directly as done.

string

Allowed values: queued running done error

request

object

type

Task type. Only serp_full (full organic SERP) is available today.

string

default: serp_full

Allowed values: serp_full

keyword

required

The search query.

string

>= 1 characters

region

required

Region code from GET /regions.

string

device

string

default: desktop

Allowed values: desktop mobile tablet

depth

Number of result pages to crawl (10 results per page).

integer

default: 1 >= 1 <= 5

result

One of:

object

object

keyword

string

region

string

device

string

total_results

Approximate total results reported by Google.

integer

items

Array<object>

object

position

1-based organic rank.

integer

url

string format: uri

title

string

snippet

string | null

displayed_url

string

null

null

error

One of:

object

object

code

Stable machine-readable code

string

message

string

task_id

string | null format: uuid

null

null

cost

Credits charged for this task.

integer

created_at

string format: date-time

started_at

string | null format: date-time

finished_at

string | null format: date-time

Examples

Exampledone

{
  "task_id": "58e6ea50-492b-494c-9767-f6f1396e9298",
  "type": "serp_full",
  "status": "done",
  "request": {
    "keyword": "best running shoes",
    "region": "us",
    "device": "desktop",
    "depth": 1
  },
  "result": {
    "keyword": "best running shoes",
    "region": "us",
    "device": "desktop",
    "total_results": 1010,
    "items": [
      {
        "position": 1,
        "url": "https://example.com/best-running-shoes",
        "title": "Best Running Shoes — 2026 Guide",
        "snippet": "A representative organic result.",
        "displayed_url": "example.com"
      }
    ]
  },
  "error": null,
  "cost": 1,
  "created_at": "2026-08-03T11:23:22Z",
  "started_at": "2026-08-03T11:23:22Z",
  "finished_at": "2026-08-03T11:23:23Z"
}

401

Missing or invalid API key.

Media typeapplication/json

object

error

object

code

Stable machine-readable code

string

message

string

task_id

string | null format: uuid

Examples

{
  "error": {
    "code": "apikeys.missing",
    "message": "API key required"
  }
}

{
  "error": {
    "code": "apikeys.invalid",
    "message": "API key is invalid or revoked"
  }
}

404

No task with that id for your organization.

Media typeapplication/json

object

error

object

code

Stable machine-readable code

string

message

string

task_id

string | null format: uuid

Examples

Exampledefault

{
  "error": {
    "code": "serpapi.task_not_found",
    "message": "Task not found"
  }
}

429

Per-key rate limit exceeded.

Media typeapplication/json

object

error

object

code

Stable machine-readable code

string

message

string

task_id

string | null format: uuid

Examples

Exampledefault

{
  "error": {
    "code": "serpapi.rate_limited",
    "message": "Rate limit exceeded"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying (on 429).

X-RateLimit-Limit

integer

Requests allowed per minute for this key.

X-RateLimit-Remaining

integer

Requests remaining in the current window.

X-RateLimit-Reset

integer

Unix epoch second when the window resets.