---
title: "Position of a domain for a keyword in the top N (default 100; priced like /v1/search depth, 7 credits for 100)"
method: POST
path: "/v1/rank"
---

# Position of a domain for a keyword in the top N (default 100; priced like /v1/search depth, 7 credits for 100)

`POST /v1/rank`

## Request

- Base URL: `https://api.serpkite.com`
- URL: `https://api.serpkite.com/v1/rank`
- Auth: HTTP bearer

## Request body

- RankRequest
  - `q` string, required
  - `domain` string, required: Domain to find, e.g. "example.com" (subdomains match)
  - `num` 10 | 20 | 30 | 50 | 100
  - `country` string
  - `language` string
  - `location` string
  - `device` 'desktop' | 'mobile'
  - `max_age` integer

## Response `200`

OK

- RankResponse
  - `request` RequestEcho, required: The normalised request that produced this response (defaults filled in)
    - `endpoint` string, required
    - `engine` union, required: The engine policy as asked (google, auto, one provider or a list)
      - string
      - string[]
    - `q` string
    - `url` string
    - `country` string
    - `language` string
    - `location` string
    - `num` integer
    - `page` integer
    - `device` string
    - `autocorrect` boolean
    - `tbs` string
    - `start_date` string, date
    - `end_date` string, date
    - `safe` string
    - `place_id` string
    - `cid` string
    - `fid` string
    - `sort` string
    - `include_content` integer
    - `format` string
    - `include_domains` string[]
    - `exclude_domains` string[]
    - `boost_domains` string[]
    - `highlights` boolean
  - `domain` string, required
  - `position` integer, nullable, required: Best organic position
  - `matches` object[], required
    - `position` integer, required
    - `title` string, required
    - `link` string, required
  - `checked` integer, required: Organic results inspected
  - `meta` Meta, required
    - `request_id` string, required
    - `credits_used` number, required
    - `engine` string: The provider that produced the result (`consensus` for a merged engine=consensus answer)
    - `route` RouteStep[]: Provider attempts in order (fresh results only; absent on cache hits). With engine=consensus, every provider started; ones stopped early are `canceled`, ones cut off by the deadline `timeout`
      - `provider` string, required
      - `outcome` 'ok' | 'partial' | 'empty' | 'soft_empty' | 'blocked' | 'timeout' | 'error' | 'unsupported' | 'bad_param' | 'bad_target' | 'canceled', required
      - `ms` integer, required: Duration of the attempt in milliseconds
    - `cached` boolean, required
    - `cached_at` string, date-time
    - `resolved_urls` boolean
    - `parse_quality` 'ok' | 'partial' | 'empty'
    - `latency_ms` integer

## Other responses

- `400`: Error
- `401`: Error
- `402`: Error
- `403`: Error
- `429`: Error
- `503`: Temporarily unavailable, not billed, safe to retry after `Retry-After`. Codes: `upstream_error` (the upstream page couldn't be fetched or parsed), `upstream_blocked` (the upstream is rate limiting us), `upstream_timeout` (the search took too long), `unavailable` (endpoint or dependency down). The API never sends 502 or 504.

---

[API](https://skmtc.dev/serpkite/apis/serpkite-serp-api.md) · [All operations](https://skmtc.dev/serpkite/apis/serpkite-serp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/serpkite/apis/serpkite-serp-api/revisions/f2c6dd05cfc5?raw)