First request

Submit an audit

The public REST API lets you run audits and read the gaps over plain HTTP. Everything is authenticated with an API key (see the next page). An audit takes a single keyword and its market:

curl -X POST https://api.graphranks.com/v1/audits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "knowledge graph seo"}'

POST /v1/audits is asynchronous — it meters one check, starts the run, and returns a run_id immediately with 202 Accepted. Add serp_location and serp_language to set the market, or compare_url / compare_text to fold your own page in as coverage.

{
  "run_id": "a1b2c3…",
  "status": "running"
}

Poll for the result

The pipeline scrapes the top-ranking pages and builds the graph in the background, so poll GET /v1/runs/{run_id}/status until status is done (it moves queued → running → done, or failed with an error). Then read the gaps:

curl https://api.graphranks.com/v1/runs/a1b2c3…/gaps \
  -H "Authorization: Bearer YOUR_API_KEY"

The gaps

GET /v1/runs/{run_id}/gaps returns the answer: a summary and the ranked gaps. Each gap is a backed-assertion fact — an oracle (search demand, competitor consensus, or graph topology) asserts a connection a target lacks — carrying its source, kind, quadrant, score, and the evidence behind it.

{
  "keyword": "knowledge graph seo",
  "summary": {
    "total": 42,
    "by_quadrant": { "opportunity": 18, "catchup": 24 }
  },
  "compare": null,
  "gaps": [
    {
      "id": "9f2a…",
      "source": "consensus",
      "kind": "missing_connection",
      "quadrant": "catchup",
      "a": "entity resolution",
      "b": "schema",
      "score": 8.7,
      "consensus": 6,
      "evidence": ["held by 6 of 20 ranking pages"]
    }
  ]
}

For the whole stored run — including the graph the gaps were derived from — fetch GET /v1/runs/{run_id}.