Skip to content
Saturn

API reference

The Saturn REST API.

Send events, query metrics and manage alerts over HTTPS with predictable, resource-oriented URLs and JSON everywhere.

v1Base URL https://api.saturn.app/v1

Authentication

The Saturn API is organised around REST. All requests use HTTPS and authenticate with a bearer token. Create keys in Settings → API keys and scope them to what they need.

The examples on this page read the base URL and your key from two shell variables, $API and $KEY:

Terminal
export API=https://api.saturn.app/v1
export KEY=sk_live_••••••••

curl "$API/metrics" \
  -H "Authorization: Bearer $KEY"

Errors

Saturn uses conventional HTTP status codes. Errors return a JSON body with a machine-readable code and a human message.

StatusCodeMeaning
400invalid_requestA parameter is missing or malformed
401unauthorizedThe key is missing, revoked or wrong
403forbiddenThe key lacks the required scope
404not_foundThe resource doesn't exist
429rate_limitedToo many requests — retry after the given delay
500server_errorSomething went wrong on our side
Response · 401
{
  "error": {
    "code": "unauthorized",
    "message": "API key was revoked"
  }
}

Rate limits

Each key can make 100 requests per second, with bursts up to 500. Event ingestion is limited separately at 10,000 events per second per workspace. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset headers.

Send an event

POST/v1/events

Records a single event. Events are visible on live charts within a second.

ParameterTypeDescription
eventstringEvent name, e.g. checkout_completed. Required.
user_idstringYour stable identifier for the user.
timestampISO 8601Defaults to the time of the request.
propertiesobjectUp to 255 key–value pairs.
Request
curl -X POST "$API/events" \
  -H "Authorization: Bearer $KEY" \
  -d '{
    "event": "checkout_completed",
    "user_id": "u_8f2c"
  }'
Response · 200
{
  "id": "evt_01J9Z4",
  "received_at": "2026-11-06T10:42:07Z"
}

Batch events

POST/v1/events/batch

Sends up to 1,000 events in one request. The whole batch is accepted or rejected.

ParameterTypeDescription
eventsarrayAn array of event objects, as above. Required.
Request
curl -X POST "$API/events/batch" \
  -H "Authorization: Bearer $KEY" \
  -d @events.json
Response · 200
{
  "accepted": 1000,
  "rejected": 0
}

List metrics

GET/v1/metrics

Returns the metrics defined in the workspace, newest first, 50 per page.

ParameterTypeDescription
cursorstringCursor from the previous page.
ownerstringOnly metrics owned by this team.
Request
curl -G "$API/metrics" \
  -H "Authorization: Bearer $KEY" \
  -d owner=growth-team
Response · 200
{
  "data": [
    { "name": "weekly_active_users" }
  ],
  "next_cursor": null
}

Query a metric

GET/v1/metrics/{name}/query

Returns a time series for a metric over a range, at the interval you choose.

ParameterTypeDescription
fromISO 8601Start of the range. Required.
toISO 8601End of the range. Defaults to now.
intervalstring1m, 1h, 1d or 1w.
Request
METRIC=weekly_active_users

curl -G "$API/metrics/$METRIC/query" \
  -H "Authorization: Bearer $KEY" \
  -d from=2026-10-01 \
  -d interval=1d
Response · 200
{
  "series": [
    { "t": "2026-10-01", "v": 48210 },
    { "t": "2026-10-02", "v": 49102 }
  ]
}

Create an alert

POST/v1/alerts

Creates a threshold or anomaly alert on a metric.

ParameterTypeDescription
metricstringMetric name. Required.
typestringthreshold or anomaly. Required.
notifyarrayDelivery targets, e.g. slack:#growth.
Request
curl -X POST "$API/alerts" \
  -H "Authorization: Bearer $KEY" \
  -d '{
    "metric": "p95_latency",
    "type": "anomaly",
    "notify": ["slack:#oncall"]
  }'
Response · 200
{
  "id": "alt_7Q2M",
  "status": "active"
}

Delete an alert

DELETE/v1/alerts/{id}

Permanently deletes an alert. Its history stays in the audit log.

Request
curl -X DELETE \
  "$API/alerts/alt_7Q2M" \
  -H "Authorization: Bearer $KEY"
Response · 200
{
  "deleted": true
}