Submit a SERP task

POST

/serp/tasks

curl --request POST \
  --url https://api.seo-checker.com.ua/v1/serp/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "keyword": "best running shoes", "region": "us", "device": "desktop", "depth": 1 }'

• Production
• Development

Queue a full organic SERP crawl for a keyword in a region on a device. Returns 202 with a task_id and status: "queued". Poll GET /serp/tasks/{id} until status is done or error.

Billing: the task cost (1 credit per keyword) is charged on create, including cache hits (a fresh identical crawl is reused but still billed). A terminal error is automatically refunded. Insufficient balance returns 402 and no task is created.

Authorizations

• apiKey

Request Body^required

Media typeapplication/json

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

Examples

Exampledefault

{
  "keyword": "best running shoes",
  "region": "us",
  "device": "desktop",
  "depth": 1
}

Responses

202

Task accepted and queued (or served immediately from cache as done).

Media typeapplication/json

object

task_id

string format: uuid

status

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

string

Allowed values: queued running done error

Examples

Examplequeued

{
  "task_id": "58e6ea50-492b-494c-9767-f6f1396e9298",
  "status": "queued"
}

Headers

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.

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"
  }
}

402

Not enough credits to run the task. No task is created.

Media typeapplication/json

object

error

object

code

Stable machine-readable code

string

message

string

task_id

string | null format: uuid

Examples

Exampledefault

{
  "error": {
    "code": "payments.insufficient_balance",
    "message": "Insufficient credit balance"
  }
}

422

The request failed validation.

Media typeapplication/json

object

error

object

code

Stable machine-readable code

string

message

string

task_id

string | null format: uuid

Examples

{
  "error": {
    "code": "serpapi.region_unknown",
    "message": "Unknown region code"
  }
}

{
  "error": {
    "code": "serpapi.device_invalid",
    "message": "device must be desktop",
    "mobile or tablet": null
  }
}

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.