Start building

Your first search request.

Send a query and read the result of a completed job. You need an AgentSEO account, an API key with available credits, and a terminal with cURL.

These examples use the United States (location_code: 2840). Search consumes your plan’s credits. Check current plans and usage before running larger batches.

1. Create and store an API key

Open API keys, create a key, and store it as AGENTSEO_API_KEY in your server-side environment. You can also try the API in the Playground.

Environment variable setup

# Replace the placeholder locally. Never commit your real key.
export AGENTSEO_API_KEY='YOUR_API_KEY'

REST uses the x-api-key header. Do not put the key in browser code, a public repository, a URL, or a shared prompt.

2. Submit one search

Submit a search job

curl --fail-with-body https://www.agentseo.dev/api/v1/search \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"seo api","limit":5,"location_code":2840}'

The normal response is HTTP 202. Store the returned jobId. This illustrative response shows the queue fields; your ID will differ.

Illustrative queued response

{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "queued",
  "message": "Search job enqueued",
  "poll_url": "/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000",
  "events_url": "/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/events",
  "retry_after_seconds": 2
}

3. Poll for the result

Replace YOUR_RETURNED_JOB_ID with the ID from step 2. Wait for the recommended interval before polling again. Do not submit another search just because the first one is still running.

Poll the returned job

export AGENTSEO_JOB_ID='YOUR_RETURNED_JOB_ID'
curl --fail-with-body "https://www.agentseo.dev/api/v1/jobs/$AGENTSEO_JOB_ID" \
  -H "x-api-key: $AGENTSEO_API_KEY"

Job status	What to do
queued / processing / retrying	Keep the job ID and poll again within your application’s deadline.
completed	Read `result`; inspect evidence and limitations before using it.
failed	Stop polling. Inspect `error.code`, `error.message`, and `error.retryable`.

An HTTP 200 from the polling endpoint means the status request succeeded; check status to know whether the analysis succeeded. Returned item count can be below your requested limit.

Read the complete async lifecycle and bounded polling example →

If the first request fails

401: confirm the environment variable is set and the key reaches x-api-key.
400: check the JSON body against the search parameters.
402: inspect available credits in the dashboard.
429: wait until the rate-limit reset; avoid a tight retry loop.
Job failed: read the job error instead of assuming another poll will restart it.

Errors and limits · Build a multi-step workflow · Inspect measured responses

Your first search request.

1. Create and store an API key

2. Submit one search

3. Poll for the result

4. Choose your runtime

JavaScript

Python

MCP

If the first request fails