KleoGEO data in your own tools

Quick start

1. 1

   Create a key

   Open API keys in your account and create a key with the permissions you need. The key is shown once — keep it in a secret manager, not in code.

2. 2

   Authorize requests

   Send the key in the header of every request. Only API keys are accepted here: passwords and browser sign-in do not work.

   Authorization: Bearer geo_live_…

3. 3

   Make the first call

   Check the key: GET /v1/me returns your organization, plan limits and the key’s permissions.

   curl https://api.kleogeo.ru/v1/me \
     -H "Authorization: Bearer $KLEOGEO_API_KEY"

Examples

curl https://api.kleogeo.ru/v1/projects \
  -H "Authorization: Bearer $KLEOGEO_API_KEY"

curl "https://api.kleogeo.ru/v1/projects/$PROJECT_ID/metrics/visibility?granularity=week&from=2026-09-01" \
  -H "Authorization: Bearer $KLEOGEO_API_KEY"

{
  "analyzer_version": "0.4.0",
  "series": [
    {
      "brand_id": "0199e8a4-1f6b-7c2e-9a41-3d5b7f0c2a11",
      "brand_name": "Acme",
      "is_primary": true,
      "points": [
        {
          "t": "2026-10-06", "provider": "all",
          "n": 150, "mentioned": 63,
          "share": 0.42, "ci_low": 0.344, "ci_high": 0.5
        }
      ]
    }
  ]
}

curl -fSL -o mentions.csv \
  "https://api.kleogeo.ru/v1/projects/$PROJECT_ID/exports/mentions.csv?from=2026-09-01" \
  -H "Authorization: Bearer $KLEOGEO_API_KEY"

curl -X POST "https://api.kleogeo.ru/v1/projects/$PROJECT_ID/runs" \
  -H "Authorization: Bearer $KLEOGEO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

# then check the status
curl "https://api.kleogeo.ru/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $KLEOGEO_API_KEY"

Permissions

A key sees only its own organization’s data and only what its permissions allow. Grant the minimum you need and use a separate key per integration.

GET /v1/me works with any valid key. A missing permission returns 403 insufficient_scope.

Limits and retries

• 10 requests per second per key (short bursts up to 20) and a shared limit of 20 per second per organization.
• Every response shows the key’s limit: RateLimit-Policy: "api-key";q=20;w=2 and RateLimit: "api-key";r=17;t=1 — requests left right now (r) and seconds until the limit is fully restored (t).
• Above the limit you get 429 rate_limited with a Retry-After header (seconds). Wait that long and retry.
• 503 server_busy and 503 upstream_timeout carry Retry-After too: GET requests are safe to retry, POST requests with the same Idempotency-Key.
• Request bodies are limited to 1 MB. Skip downloading unchanged GET responses: send If-None-Match with the ETag value and get 304.

Errors

Every error has the same shape. Rely on code — it never changes; message is an English explanation for your logs. Some errors add details such as limit and current.

{
  "error": {
    "code": "rate_limited",
    "message": "too many requests, slow down"
  }
}

Conventions