# Documentation

Get a key, make one call, read what comes back. Five minutes. After that: the contract, a reference page per endpoint, and worked examples.

## 1. Get a key

Sign up at https://seofetch.com/app/ and create a key from the dashboard. Every account starts with 1,000 free credits. The request below costs 1, so that is 1,000 runs before you pay for anything.

## 2. Your first request

Swap in your key and run it:

```bash
curl https://api.seofetch.com/v1/search \
  -H "Authorization: Bearer sof_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "best running shoes"}'
```

## 3. Read the envelope

Every endpoint wraps its results in the same six fields: id, request_id, object, created_at, elapsed_ms, credits. The results themselves are under data. Learn this once and you can read all twenty-one endpoints.

credits.charged is what the call cost (0 on a replay). credits.balance is what's left. Errors, timeouts, rate limits and refunds are on The Contract.

```json
{
  "id": "srch_7f34stnlffnsbalonq66dpuj",
  "request_id": "req_7e5465ge5fjmziqx5dyueaqyvy",
  "object": "search",
  "created_at": "2026-07-29T12:00:00Z",
  "elapsed_ms": 244,
  "credits": {
    "charged": 1,
    "balance": 9857
  },
  "data": {
    "query": "best running shoes",
    "engine": "google",
    "location": 2840,
    "language": "en",
    "device": "desktop",
    "total_results": 84900000,
    "serp_url": "https://www.google.com/search?q=best+running+shoes",
    "result_types": [
      "organic"
    ],
    "results_count": 10,
    "items": [
      {
        "type": "organic",
        "rank": 1,
        "page": 1,
        "domain": "example.com",
        "title": "The 12 Best Running Shoes",
        "url": "https://example.com/best-running-shoes",
        "description": "Our team tested 40 pairs...",
        "displayed_link": "example.com › reviews › shoes",
        "date": null,
        "site_name": "Example Running Co.",
        "rating": {
          "value": 4.6,
          "votes": 1284,
          "max": 5
        },
        "sitelinks": [
          {
            "title": "Best Trail Running Shoes",
            "url": "https://example.com/best-running-shoes/trail",
            "description": null
          },
          {
            "title": "Best Budget Running Shoes",
            "url": "https://example.com/best-running-shoes/budget",
            "description": null
          }
        ],
        "price": null,
        "highlighted_words": [
          "running shoes"
        ]
      }
    ]
  }
}
```

## 4. Retries are free

You sent no idempotency key above. That's fine: success responses carry a request_id, and so does the 504 you get if a job outlives your connection. Resend the same body with that request_id and you're never charged twice. While the job is still running, the retry waits for it. Once it has finished you get the exact stored result back for 6 hours, a cache read, uncharged. Past that it's a 409, so mint a new key. Timing and mechanics are on The Contract.

## 5. What's next

That's the quickstart. The Contract has the exact rules, each of the twenty-one endpoints has a reference page, and the examples are complete scripts you can copy. Writing an agent? Read For agents next.

## 6. For agents

Every page here is also plain Markdown. Start with https://docs.seofetch.com/overview.md, a short brief rather than the whole corpus. https://docs.seofetch.com/llms.txt lists every page; https://docs.seofetch.com/llms-full.txt is the entire corpus in one fetch: this page, The Contract, the Changelog, and all twenty-one endpoint references.

Three ways to ask for Markdown instead of HTML: ?format=md on the query string, a .md suffix on the URL (https://docs.seofetch.com/the-contract.md), or an Accept: text/markdown header. All three return the same Markdown.

Request and response schemas are published as OpenAPI: https://api.seofetch.com/v1/openapi.json.

One rule for unattended retries. If your process might die before it reads the response, bring your own key up front; a lost response means no request_id to recover. If the response did arrive, its request_id is your replay key. Details on The Contract.

```bash
curl "https://docs.seofetch.com/the-contract/?format=md"
curl "https://docs.seofetch.com/the-contract.md"
curl -H "Accept: text/markdown" "https://docs.seofetch.com/the-contract/"
```