HTTP API reference
These endpoints receive data. None of them reads data. All paths are on your instance’s address, such as https://analytics.example.com.
| Endpoint | Key | Use |
|---|---|---|
POST /api/events |
Public key, in the body | Browser events. The tracker sends these. |
POST /api/server-events |
Secret key, in the header | Events from your server |
PUT /api/source-maps |
Secret key, in the header | Source map uploads |
POST /v1/traces, /v1/logs, /v1/metrics |
Secret key, in the header | OpenTelemetry data |
GET /api/health |
None | Answers {"status":"ok"} while the API runs |
Errors have a JSON body with an error code and a message.
POST /api/events
Section titled “POST /api/events”Browser events. The tracker sends these for you. Use this format only if you write your own client.
{ "v": 1, "key": "pk_00000000000000000000000000000000", "sentAt": 1794823396705, "environment": "production", "release": "1.4.2", "events": [ { "id": "0b9c6a4e-5d1f-4b8a-9a43-2f7d1c3e8b10", "name": "pageview", "occurredAt": 1794823394705, "url": "https://example.com/pricing?utm_source=newsletter", "referrer": "https://news.example.org/item", "properties": { "plan": "free" } } ]}| Field | Meaning |
|---|---|
v |
Required. The format version: 1. |
key |
Required. The project’s public key. |
sentAt |
Required. When the batch was sent, in milliseconds since 1970, by the sender’s clock. |
environment, release |
Optional. For every event of the batch. |
touch |
Optional. true when the device has a touchscreen. |
events |
Required. 1 to 50 events. |
events[].id |
Required. A UUID that the sender makes. A retry sends the same ID. |
events[].name |
Required. pageview, or a custom name. |
events[].occurredAt |
Required. When the event happened, in milliseconds, by the sender’s clock. |
events[].url |
Required. The page’s http or https address. |
events[].referrer |
Optional. The referring page. |
events[].userId |
Optional. Your app’s ID for the signed-in user. |
events[].userSignature |
Optional. The user ID’s signature: 64 hex digits. |
events[].properties |
Optional. A flat object. |
- Send the body as
text/plain. A browser then sends it without a preflight request.application/jsonalso works. - The instance trusts only the difference between
sentAtandoccurredAt, not the sender’s clock. It places each event that long before the batch arrived. - Events that happened more than 24 hours before the batch was sent are not stored. The answer counts them in
tooOld. - The page’s hostname, and the
Originheader when there is one, must be in the project’s allowed hostnames. - One invalid event makes the whole batch fail. Nothing from it is stored.
- Requests that announce a bot in their
User-Agent, have noUser-Agent, or come from a data center (when the project ignores data centers, the default) are answered 202 and not stored. The answer counts them inbots.
| Status | error |
Meaning | Send again? |
|---|---|---|---|
| 202 | none | Stored. The body is { "stored", "tooOld", "bots", "unverifiedUsers" }. |
No |
| 400 | invalid_request |
The batch breaks a rule. | No |
| 403 | unknown_key, origin_not_allowed, hostname_not_allowed |
Wrong key, or a site that the project does not allow | No |
| 413 | payload_too_large |
The body is over 64 KB. | No. Send smaller batches. |
| 415 | unsupported_media_type |
Not text/plain or application/json |
No |
| 429 | rate_limited |
Too many requests or events | Yes, after Retry-After |
| 503 | storage_unavailable |
Nothing was stored. | Yes, after Retry-After |
The instance answers 202 only after the events are written. A retry with the same event IDs is stored one time.
POST /api/server-events
Section titled “POST /api/server-events”Events from your own server, such as a payment. They belong to a user, and they show in that user’s activity, not in web analytics.
POST /api/server-events HTTP/1.1Host: analytics.example.comAuthorization: Bearer sk_…Content-Type: application/json
{ "v": 1, "environment": "production", "release": "api@2.3.0", "events": [ { "id": "8c1f0a52-3d4e-4f60-9b7a-1c2d3e4f5a6b", "name": "subscription_started", "occurredAt": 1794823396705, "userId": "42", "path": "/checkout", "properties": { "plan": "team" } } ]}| Field | Meaning |
|---|---|
v |
Required. 1. |
environment, release |
Optional. For every event of the batch. |
events |
Required. 1 to 50 events. |
events[].id |
Required. A UUID. A retry must send the same ID and the same occurredAt. |
events[].name |
Required. Not pageview, engagement, error, or vitals. |
events[].occurredAt |
Required. When it happened, in milliseconds since 1970. The instance trusts your server’s clock. |
events[].userId |
Required. Your app’s ID for the user. It needs no signature. |
events[].path |
Optional. A path that starts with /, without a query string or fragment. |
events[].properties |
Optional. A flat object, as for browser events. |
- The secret key must stay on your server. The endpoint sends no CORS headers.
- An
occurredAtmore than 5 minutes in the future is refused (400). An event more than 24 hours old is counted intooOldand not stored. - No location, browser, or device is recorded.
- Server events use the same budget as the project’s browser events.
The answers are those of /api/events, with these differences: 401 (unauthorized or unknown_key) for a missing, malformed, or unknown key, in place of 403. The 202 body is { "stored", "tooOld" }. Send again only after 429 and 503.
PUT /api/source-maps
Section titled “PUT /api/source-maps”Uploads one source map. See Upload source maps.
PUT /api/source-maps?release=1.4.2&path=/assets/index-4f3a.js HTTP/1.1Host: analytics.example.comAuthorization: Bearer sk_…Content-Type: application/jsonContent-Encoding: gzip| Parameter | Meaning |
|---|---|
release |
Required. The data-release of the build. 1 to 200 characters, without spaces. |
path |
Required. The minified file’s path as the browser loads it, without the origin. Up to 1,024 characters. |
| Body | The source map. Content-Type: application/json. Content-Encoding: gzip is optional. |
| Status | Meaning |
|---|---|
| 201 | Stored a new map. |
| 200 | Replaced the release’s earlier map of the same file. |
| 400 | Not a source map that Ottertrail reads, or a bad path or gzip body. |
| 401 | A missing, malformed, or unknown secret key. |
| 409 | The instance’s source map storage is full. |
| 413 | Over 25 MiB after it is unpacked. |
| 415 | A Content-Encoding other than gzip. |
| 429 | Too many requests from this address. Send again after Retry-After. |
| 503 | Source maps are off on this instance, or the instance is busy. When it sends Retry-After, send again after that time. |
OpenTelemetry: /v1/traces, /v1/logs, /v1/metrics
Section titled “OpenTelemetry: /v1/traces, /v1/logs, /v1/metrics”OTLP over HTTP, version 1. See Send telemetry.
- Authenticate with
Authorization: Bearer sk_…. - Send protobuf (
application/x-protobuf) or JSON (application/json), compressed with gzip or not. The answer uses the request’s encoding. - gRPC, exponential histograms, and summaries are not supported.
| Status | Meaning |
|---|---|
| 200 | Stored. When some records were refused, the answer’s partial_success says how many and why. Do not send those again. |
| 400 | Not OTLP, or not the encoding that the request names. |
| 401 | No key, or a key that no project has. |
| 413 | Over 16 MiB after it is unpacked, over a million messages, or more than the project’s whole budget. Send smaller batches. |
| 415 | Another content type, or a compression other than gzip. |
| 429 | Over the project’s or the instance’s budget, or too many requests at once for the project. Send again after Retry-After. |
| 503 | The instance cannot store it now. Send again after Retry-After. |
OpenTelemetry exporters send 429, 502, 503, and 504 again by themselves, and nothing else.