Read your reports from code

https://coruve.com/api/v1

Every endpoint is a GET. The API is read-only by construction: there is no write path behind a read key, and sending events stays where it always was, at the ingest endpoint.

curl -s -H "Authorization: Bearer $CORUVE_API_KEY" \
  "https://coruve.com/api/v1/datasets" | jq

/datasets lists every dataset with its parameters and tells you which ones your plan can actually read — so a client discovers a plan gate before production does.

Project Settings → API keys → Read reports. Read keys start with rk_live_ and are shown once, at creation. They are stored only as a SHA-256 hash — nobody, including us, can recover one. Revocation is immediate.

# Preferred
curl -H "Authorization: Bearer rk_live_YOUR_KEY" \
  "https://coruve.com/api/v1/pages?from=2026-07-01&to=2026-07-31"

# Also accepted — the same header the ingest API uses
curl -H "X-Coruve-Key: rk_live_YOUR_KEY" \
  "https://coruve.com/api/v1/pages"

The key is never read from the query string. A credential in a URL ends up in proxy logs, browser history and Referer headers, and this is the credential that can read your data.

There is no project selector to get wrong — the key determines which project you read. You may pass ?projectId=… to assert which project you meant; if it disagrees with the key you get 403 PROJECT_MISMATCH rather than a report about the wrong site.

• from, to — an ISO 8601 instant or a bare YYYY-MM-DD, which widens to the whole day. Defaults to the last 30 days. One request may span at most 366 days; read a longer history a window at a time, or use the CSV export.
• limit — rows per page. Default 100, maximum 1,000.
• offset — rows to skip. offset + limit must not exceed 5,000.
• projectId — optional assertion, checked against your key.

Spelled exactly as they are on the dashboard, so a filtered screen and a filtered API call return the same number:

curl -H "Authorization: Bearer $CORUVE_API_KEY" \
  "https://coruve.com/api/v1/pages?country=DE&channel=ai&utmCampaign=summer&limit=20"

Available on every dataset — 17 of them, listed here from the same constant the dashboard's own chip bar is built from, so this list cannot fall behind the product:

country, region, city, device, browser, os, viewport, channel, source, path, entryPath, exitPath, utmSource, utmMedium, utmCampaign, aiSource, frustration.

A dataset that cannot honour a filter says so in meta.ignored rather than answering a wider question quietly.

?segment=<id> applies a segment you saved in the dashboard. It carries two things the filter vocabulary above cannot spell: the segment's name, which comes back in meta.segment so a script can stamp a row “under the Paying customers segment” rather than an opaque id, and its behavioural conditions — “sessions that started checkout and never bought” — which are computed in the store from a step predicate and have no query-string spelling at all.

Ids are resolved server-side and project-scoped: an id from another project is 400 INVALID_REQUEST, not found-and-then-checked.

You may send both. Where a saved segment and an explicit filter name the same dimension, the explicit filter wins — the same precedence the dashboard has when you apply a segment and then change a chip, and the alternative (ANDing two values of one dimension) is a request that can only ever return nothing. Every dimension where that happened is named in meta.segment.overridden, because silent precedence is the failure that field exists to prevent.

# The saved segment says country=DE; the chip says AT. AT wins,
# and meta.segment.overridden comes back as ["country"].
curl -H "Authorization: Bearer $CORUVE_API_KEY" \
  "https://coruve.com/api/v1/pages?segment=seg_abc&country=AT"

Each of these belongs to the datasets named beside it; the endpoint table above says which ones a given dataset takes, and this is what the values mean. Sending one to a dataset that does not use it is not an error — it comes back named in meta.ignored.

A parameter we have never heard of is a 400, never a silent no-op. But a parameter that is real and simply does not apply to the dataset you asked for used to be accepted in silence: ?country=DE on /events returned every label on the project, under a filter you believed had been applied.

Those now come back named in meta.ignored. The field is absent when there is nothing to report — it is there to be conspicuous when it appears, and a request that carries one is a request worth fixing.

{
  "data": [ /* every saved segment — country did not narrow anything */ ],
  "meta": {
    "dataset": "segments",
    "ignored": ["country"]
  }
}

A request that carried ?segment= gets the segment back by name, not just the id it sent. overridden names every dimension where an explicit filter replaced one of the segment's own clauses; it is absent when nothing was overridden.

{
  "data": [ /* pages, under the segment with country forced to AT */ ],
  "meta": {
    "dataset": "pages",
    "segment": { "id": "seg_abc", "name": "Paying customers", "overridden": ["country"] }
  }
}

This is the field most worth reading, because ignoring it is how a caller draws exactly the wrong conclusion. An empty data array means two different things and they look identical over the wire: nothing happened, and this question cannot be answered on your data. When it is the second, the envelope says so in meta.notice and data is empty.

/retention is the case that forced the field and the only dataset that produces one today. Coruve's anonymous visitor identifier rotates at UTC midnight, so cross-day retention is measurable only for visitors your site has called identify() on. On a project with too few of them there is no honest cohort grid to return — and a caller charting data.length without reading notice draws a flat line and reports that retention collapsed.

{
  "data": [],
  "meta": {
    "dataset": "retention",
    "notice": "Retention requires identified users; see /docs/identify"
  }
}

Branch on the presence of notice before you branch on data.length. Like ignored, it is absent when there is nothing to say — a field present on every response stops being read.

On /ai-sources, verifiedVisitors and verifiedEvents are null — never 0 — when the backend could not check cryptographic signatures at all. Zero would be a measurement (“we looked and nothing was signed”); null is the truth (“we never looked”). Sum the column accordingly.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. A 429 also carries Retry-After in seconds.

The allowance is counted per project, not per key. Every key on a project draws on the same number, so the figure above is the one your project actually gets — minting a second key does not buy a second allowance. Keys are still worth splitting per integration, for revocation and for reading lastUsedAt; they just do not multiply your throughput.

Before any key is looked at there is also a per-IP ceiling of 300 requests a minute. A client presenting a valid key will never meet it.

What we noticed, what was fixed about it, and the numbers underneath — three requests, no joins against anything you have to store yourself.

KEY=rk_live_...
BASE=https://coruve.com/api/v1

curl -H "Authorization: Bearer $KEY" "$BASE/findings?status=new"
curl -H "Authorization: Bearer $KEY" "$BASE/cases?state=verified"
curl -H "Authorization: Bearer $KEY" "$BASE/overview?from=2026-08-01&to=2026-08-31"

The reason /funnels exists. Ask what funnels there are, then ask one of them for its steps — no id copied out of a browser URL.

ID=$(curl -sH "Authorization: Bearer $KEY" "$BASE/funnels" | jq -r '.data[0].id')
curl -H "Authorization: Bearer $KEY" "$BASE/funnel?funnelId=$ID"

The export endpoint is session-authenticated rather than key-authenticated, so it is for a person with a browser rather than a script. report=all hands back every report your plan includes, zipped, with a README that explains the columns. If you would rather it arrived on its own, Settings ▸ Data & export will email it every morning, week or month.

/api/export?projectId=<id>&report=all&from=2026-08-01&to=2026-08-31
/api/export?projectId=<id>&report=pages&format=json

The base path /api/v1 is stable. A change that removes a field, renames a dataset, changes a type, or changes pagination semantics is a v2. It does not ship under this path, whatever the reason.

Additive changes — a new dataset, a new optional field, a new optional parameter — ship under v1 and get a row in the changelog below. So you can write code against this version and know that nothing it reads today will stop being there.

There is no version field on a dataset response, and that is deliberate rather than an omission: the base path already carries the version, and a second copy of it in every envelope is a second thing that can disagree. The one place the version is stated in a body is GET /api/v1/datasets, which answers meta.version along with the roster your plan can read — so a client that wants to assert which version it is talking to asks that endpoint once at startup rather than parsing it out of every report.

Retiring v1 would take 12 months' notice on this page, and every response would carry a Deprecation header with the sunset date long before anything stopped working.

• 2026-08-21
  • /funnels, /goals-list, /segments, /saved-views, /annotations — the ids other endpoints need
  • /findings and /cases — what Coruve noticed, and what happened after a fix
  • /frustration and /journeys-summary — two reports that were dashboard-only
  • meta.ignored — the parameters a dataset did not use, named rather than dropped in silence

import { CoruveClient, CoruveApiError } from "@coruve/sdk";

const coruve = new CoruveClient({ apiKey: process.env.CORUVE_API_KEY! });

// Top pages, last 30 days
const pages = await coruve.get("pages", { limit: 50 });
console.log(pages.data, pages.meta.pagination);

// A summary dataset still returns an array — one element
const [overview] = (await coruve.get("overview", { from: "2026-07-01", to: "2026-07-31" })).data;

// Filters use the dashboard's vocabulary
const ai = await coruve.get("channels", { channel: "ai", country: "DE" });

// Page through a long list
for await (const rows of coruve.paginate("pages", { limit: 200 })) {
  console.log(rows.length);
}

try {
  await coruve.get("revenue");
} catch (err) {
  if (err instanceof CoruveApiError && err.code === "PLAN_UPGRADE_REQUIRED") {
    // Handle the plan gate — err.code is stable, err.message is not
  }
}

Zero dependencies, Node 18+. 429 and 5xx are retried with exponential backoff, honouring Retry-After; 401, 403, 400 and 404 throw immediately, because they are answers rather than hiccups.

import os
from coruve import CoruveClient, CoruveApiError

coruve = CoruveClient(api_key=os.environ["CORUVE_API_KEY"])

# Top pages, last 30 days
pages = coruve.get("pages", limit=50)
for row in pages.data:
    print(row["url"], row["view_count"])

# `from` is a Python keyword — pass from_ / to_
overview = coruve.get("overview", from_="2026-07-01", to_="2026-07-31")
print(overview.data[0])

# Page through a long list
for rows in coruve.paginate("pages", limit=200):
    print(len(rows), "rows")

try:
    coruve.get("revenue")
except CoruveApiError as err:
    if err.code == "PLAN_UPGRADE_REQUIRED":
        ...  # handle the plan gate

Zero dependencies, Python 3.8+. The transport is urllib behind an injectable seam, so you can route calls through httpx, requests, or your own instrumented session by passing transport=.