API reference
The Saturn REST API.
Send events, query metrics and manage alerts over HTTPS with predictable, resource-oriented URLs and JSON everywhere.
https://api.saturn.app/v1Authentication
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:
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.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A parameter is missing or malformed |
| 401 | unauthorized | The key is missing, revoked or wrong |
| 403 | forbidden | The key lacks the required scope |
| 404 | not_found | The resource doesn't exist |
| 429 | rate_limited | Too many requests — retry after the given delay |
| 500 | server_error | Something went wrong on our side |
{
"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.
| Parameter | Type | Description |
|---|---|---|
event | string | Event name, e.g. checkout_completed. Required. |
user_id | string | Your stable identifier for the user. |
timestamp | ISO 8601 | Defaults to the time of the request. |
properties | object | Up to 255 key–value pairs. |
curl -X POST "$API/events" \
-H "Authorization: Bearer $KEY" \
-d '{
"event": "checkout_completed",
"user_id": "u_8f2c"
}'
{
"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.
| Parameter | Type | Description |
|---|---|---|
events | array | An array of event objects, as above. Required. |
curl -X POST "$API/events/batch" \
-H "Authorization: Bearer $KEY" \
-d @events.json
{
"accepted": 1000,
"rejected": 0
}
List metrics
GET/v1/metrics
Returns the metrics defined in the workspace, newest first, 50 per page.
| Parameter | Type | Description |
|---|---|---|
cursor | string | Cursor from the previous page. |
owner | string | Only metrics owned by this team. |
curl -G "$API/metrics" \
-H "Authorization: Bearer $KEY" \
-d owner=growth-team
{
"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.
| Parameter | Type | Description |
|---|---|---|
from | ISO 8601 | Start of the range. Required. |
to | ISO 8601 | End of the range. Defaults to now. |
interval | string | 1m, 1h, 1d or 1w. |
METRIC=weekly_active_users
curl -G "$API/metrics/$METRIC/query" \
-H "Authorization: Bearer $KEY" \
-d from=2026-10-01 \
-d interval=1d
{
"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.
| Parameter | Type | Description |
|---|---|---|
metric | string | Metric name. Required. |
type | string | threshold or anomaly. Required. |
notify | array | Delivery targets, e.g. slack:#growth. |
curl -X POST "$API/alerts" \
-H "Authorization: Bearer $KEY" \
-d '{
"metric": "p95_latency",
"type": "anomaly",
"notify": ["slack:#oncall"]
}'
{
"id": "alt_7Q2M",
"status": "active"
}
Delete an alert
DELETE/v1/alerts/{id}
Permanently deletes an alert. Its history stays in the audit log.
curl -X DELETE \
"$API/alerts/alt_7Q2M" \
-H "Authorization: Bearer $KEY"
{
"deleted": true
}