serp_rank

Check where a domain ranks in Google's organic results for a keyword — the real SERP position, not Custom Search order. Returns the target's organic rank, the ranking URL, and every position it holds. Powered by DataForSEO.

Use Cases

Keyword Rank Tracking

Monitor where your pages rank for target keywords over time and catch ranking drops early

Competitor SERP Monitoring

Track how competitor domains rank for the keywords that matter to your business

SEO Position Audits

Audit organic positions across a keyword list to prioritize on-page and content work

Local & Device SEO Checks

Compare rankings by location and by desktop vs. mobile to spot geo or device gaps

Rank-Tracking Dashboards

Feed daily organic positions into your own dashboards and reporting pipelines

Endpoint

POST/api/v1/tools/serp_rank

Auth Required

1 req/s on Free plan

5 credits

Parameters

Name	Type	Required	Default	Description
keyword	string	Required	-	The search query to check ranking for Example: managed wordpress hosting
target	string	Required	-	Domain or URL to locate in the results. Matched by host, not exact URL: a URL is reduced to its host, and any page on that host or its subdomains counts Example: example.com
depth	number	Optional	30	How many results to scan (10-200, default 30); deeper scans take longer. Credits stay at 5 at any depth Example: 100
device	string	Optional	desktop	Device to emulate: "desktop" or "mobile" Example: mobile
location_name	string	Optional	United States	Location, e.g. 'United States' or 'London,England,United Kingdom' Example: United States
location_code	number	Optional	-	Numeric DataForSEO location code (overrides location_name) Example: 2840
language_code	string	Optional	en	Language code (e.g. 'en') Example: en

serp_rank measures true organic position, not Custom Search ordering. Depth controls how many results are scanned; the charge is 5 credits at any depth. Use location_name/location_code and device to check geo- and device-specific rankings. One lookup is one sample: Google can return a different result set for the same query minutes apart, so compare several lookups, ideally on different days, before reading a change in rank.

Request Examples

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/serp_rank \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "managed wordpress hosting",
    "target": "example.com",
    "depth": 100,
    "device": "desktop",
    "location_name": "United States",
    "language_code": "en"
  }'

Response Example

200 OK6,200ms

{
  "success": true,
  "data": {
    "keyword": "managed wordpress hosting",
    "target": "example.com",
    "location": "United States",
    "language": "en",
    "device": "desktop",
    "depth": 30,
    "found": true,
    "rank": 3,
    "url": "https://example.com/",
    "all_positions": [
      3,
      27
    ],
    "results_scanned": 30,
    "se_results_count": 1370000,
    "check_url": "https://www.google.com/search?q=managed+wordpress+hosting&num=30&hl=en&gl=US",
    "checked_at": "2026-07-01T14:30:00Z"
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 6200
}

Field Descriptions

data.rankBest organic position (null if the target is not found within depth)

data.urlThe ranking URL that holds the best position

data.all_positionsEvery organic position the target holds within the scanned depth

data.foundWhether the target appeared within the scanned depth

data.se_results_countGoogle's own result count for the query. Two lookups with very different counts came from different result sets

data.check_urlThe Google results page DataForSEO checked, to view the SERP yourself

credits_usedFixed 5 credits per lookup, at any depth

processing_timeLookups typically take 5-15 seconds

Error Handling

Missing Keyword or Target (400 Bad Request)

Both keyword and target are required. Provide a search query and a domain or URL.

Invalid Depth (400 Bad Request)

Depth must be between 10 and 200. Larger depths scan more results.

Invalid Device (400 Bad Request)

Device must be "desktop" or "mobile".

Quota Exceeded (429 Too Many Requests)

The SERP provider enforces daily limits. Upgrade your plan for higher quotas.

Provider Timeout (504 Gateway Timeout)

The SERP lookup runs a live Google query, which can exceed the time limit under load. No credits are charged — retry the request.

Lookup Unavailable (502 / 503)

The SERP provider is unreachable, rate limited, or not configured on this deployment. No credits are charged.

Pro Tip:

The target matches by host, not by exact URL: https://example.com/pricing reports the best position of any page on example.com or its subdomains, and url names the page that holds it. Pass a subdomain (blog.example.com) to narrow the match. Use location_code for precise geo-targeting when a location name is ambiguous.