Docs
Two endpoints. That’s the API.
Your CI registers releases. Your visitors’ browsers send measurements. Everything else, from reports to keys, happens in the dashboard.
Endpoint 1
POST /api/releases
Registers the commit that’s now live. Send it after every production deploy, as multipart form data.
- Auth: Authorization: Bearer with your deployment secret.
- Idempotent: sending the same commit again is safe.
- A new commit becomes the next release: v1.0.0, v1.0.1, …
- Rolling back to an earlier commit keeps its release number.
FieldsTypeMeaning
projectIdstring
requiredYour project ID.
requiredYour project ID.
commitstring
requiredThe full SHA of the deployed commit.
requiredThe full SHA of the deployed commit.
commitsfileRecent history from git log, one commit per line: hash, parents, author and subject, tab-separated. Used to list what shipped in each release.
RequestBearer: deployment secret
git log -n 100 --format='%H%x09%P%x09%an%x09%s' | curl -X POST https://codegecko.vercel.app/api/releases \ -H "Authorization: Bearer $CODEGECKO_SECRET" \ -F projectId=$CODEGECKO_PROJECT \ -F commit=$GIT_COMMIT_SHA \ -F 'commits=<-'
Response201 Created
{
"version": "v1.0.7",
"commit": "a3f9c1e…",
…
}Endpoint 2
POST /api/v1/collect
Receives batches of measurements from the collector script. You don’t call it yourself unless you’re building your own collector.
- Auth: your public key, in the body or the X-CodeGecko-Key header, and an Origin that matches the project.
- 1 to 25 measurements per request, up to 64 KB.
- Rejected batches aren’t retried. The script stops for that visit.
- Paths are templates. Query strings and fragments are never sent.
Each measurementTypeMeaning
idstring
requiredA unique ID for the reading, so a resend isn’t counted twice.
requiredA unique ID for the reading, so a resend isn’t counted twice.
metricstring
requiredLCP, INP, CLS, FCP, TTFB and the rest.
requiredLCP, INP, CLS, FCP, TTFB and the rest.
valuenumber
requiredMilliseconds, bytes or a score, by metric.
requiredMilliseconds, bytes or a score, by metric.
pathstring
requiredThe page template, like /products/:slug.
requiredThe page template, like /products/:slug.
devicestring
requiredmobile or desktop.
requiredmobile or desktop.
Request bodyPublic key
{
"projectId": "your-project-id",
"key": "cg_pub_…",
"measurements": [
{
"id": "v5-1760…",
"metric": "LCP",
"value": 2710,
"path": "/products/:slug",
"device": "mobile"
},
…
]
}Response codes
200Accepted. Returns { "accepted": n }.
400Invalid data, or the payload is too large.
401Invalid key for this project.
402Collection is turned off for this project.
403Request came from an unregistered origin, or collection is paused in Settings.
404Unknown project, or no release registered yet.
429Minute, monthly or daily new-release limit reached.
Per minute
Per project. Bursts above it get 429.
Per month
Per project, by plan.
New releases a day
Up to 20 from data-commit.
Building something custom?
Your own collector, an unusual deploy setup, or a question about the payload. Tell us what you’re building.
