# 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](https://www.agentseo.dev/pricing) before running larger batches.

## 1\. Create and store an API key

Open [API keys](https://www.agentseo.dev/dashboard/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](https://www.agentseo.dev/dashboard/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 →](https://www.agentseo.dev/docs/async-jobs)

## 4\. Choose your runtime

[

### JavaScript

Use the typed SDK in a backend service or worker.

](https://www.agentseo.dev/docs/sdks#nodejs-sdk)[

### Python

Use the client in scripts and data workflows.

](https://www.agentseo.dev/docs/sdks#python-sdk)[

### MCP

Connect a compatible coding agent or desktop client.

](https://www.agentseo.dev/docs/sdks#hosted-mcp)

## 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](https://www.agentseo.dev/docs/api-reference/search#post-search).
-   **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](https://www.agentseo.dev/docs/errors) · [Build a multi-step workflow](https://www.agentseo.dev/docs/workflows) · [Inspect measured responses](https://www.agentseo.dev/research)

---
Canonical HTML: https://www.agentseo.dev/docs/quickstart
Markdown: https://www.agentseo.dev/docs/quickstart/index.md