Uptrace JSON API

Usage Limits

Uptrace Cloud provides this API free of charge for occasional use to read small fractions of ingested data. For example, a few requests per hour to read data from the last few hours is acceptable.

If you need higher usage limits, please contact support to discuss your use case.

The API is stable and will not change without compelling reasons, such as reworking existing features or removing problematic functionality. Whenever possible, changes are made in a backward-compatible manner.

To receive notifications about API changes, please send an email to support explaining your use case.

Authentication

To use the API, you need a project ID (<project_id>) and a user authentication token (<user_token>).

You can create an authentication token on your user profile page. The token the same permissions as the user account, allowing access to the same resources.

SSO

User auth tokens do not work with Single Sign-On (SSO) because SSO requires Uptrace to redirect users to the SSO provider, which is not viable for the JSON API.

If your organization uses SSO, you need to create a separate user account and statically grant it access to projects without relying on SSO authentication.

Spans API

List Spans

Retrieve a list of spans:

shell

curl https://api.uptrace.dev/api/v1/tracing/<project_id>/spans?time_gte=2023-07-10T00:00:00Z&time_lt=2023-07-11T00:00:00Z \
  --header "Authorization: Bearer <user_token>"

Supported query parameters:

Parameter	Required	Description
`?time_gte=2023-07-10T00:00:00Z`	Yes	Time greater than or equal to `time_gte`
`?time_lt=2023-07-11T00:00:00Z`	Yes	Time less than `time_lt`
`?trace_id=17706d68ea23cf9bc8976ca57d22ee31`	No	Filter spans by trace ID
`?id=12345`	No	Filter spans by span ID
`?parent_id=12345`	No	Filter spans by parent span ID
`?limit=10000`	No	Limit number of spans

Query Groups

Aggregate spans using UQL:

shell

curl https://api.uptrace.dev/api/v1/tracing/<project_id>/groups?time_gte=2023-07-10T00:00:00Z&time_lt=2023-07-11T00:00:00Z&query=group%20by%20host_name \
  --header "Authorization: Bearer <user_token>"

Supported query parameters:

Parameter	Required	Description
`?time_gte=2023-07-10T00:00:00Z`	Yes	Time greater than or equal to `time_gte`
`?time_lt=2023-07-11T00:00:00Z`	Yes	Time less than `time_lt`
`?query=group by host_name`	No	Aggregate spans using the specified query
`?limit=10000`	No	Limit number of results
`?search=option1\|option2`	No	Search for spans containing `option1` or `option2`
`?duration_gte=10000`	No	Duration greater than or equal to N (microseconds)
`?duration_lt=100000`	No	Duration less than N (microseconds)

Request

Create a metric monitor:

shell

curl https://api2.uptrace.dev/internal/v1/projects/<project_id>/monitors \
  --request POST \
  --header "Authorization: Bearer <user_token>" \
  --header "Content-Type: application/json" \
  --data @monitor.json

Example monitor.json content:

json

{
  "name": "Number of spans per minute",
  "type": "metric",
  "notifyEveryoneByEmail": true,
  "teamIds": [123],
  "channelIds": [123],
  "repeatInterval": { "strategy": "default" },
  "params": {
    "metrics": [{ "name": "uptrace_tracing_spans", "alias": "$spans" }],
    "query": "perMin(count($spans)) as spans | where service_name = 'myservice'",
    "column": "spans",
    "minAllowedValue": 100,
    "maxAllowedValue": 1000,
    "nullsMode": "convert"
  }
}

Supported JSON fields:

Field	Type	Required	Description
`key`	String	No	Unique string to deduplicate monitors
`name`	String	Yes	Monitor name
`type`	String	Yes	Must be `metric`
`notifyEveryoneByEmail`	Boolean	No	Whether to notify everyone by email
`teamIds`	Array of integers	No	List of team IDs to notify by email (overrides `notifyEveryoneByEmail`)
`channelIds`	Array of integers	No	List of channel IDs for notifications
`params`	Object	Yes	Metric monitor parameters (see below)

Metric monitor parameters:

Parameter	Type	Required	Description
`metrics`	Array	Yes	Metrics to monitor, e.g., `[{"name": "uptrace_tracing_spans", "alias": "$spans"}]`
`query`	String	Yes	Query expression, e.g., `perMin(sum($spans)) as spans`
`column`	String	Yes	Column name to monitor, e.g., `spans`
`minAllowedValue`	Float	No*	Inclusive minimum value (values below trigger alerts)
`maxAllowedValue`	Float	No*	Inclusive maximum value (values above trigger alerts)
`groupingInterval`	Float	No	Grouping interval in milliseconds (default: 60000 for 1 minute)
`checkNumPoint`	Integer	No	Number of points to check (default: 5)
`nullsMode`	String	No	Null handling mode: `allow`, `forbid`, or `convert` (default: `allow`)
`timeOffset`	Float	No	Time offset in milliseconds, e.g., 60000 delays checks by 1 minute

* At least one of minAllowedValue or maxAllowedValue is required.

Response

json

{
  "monitor": {
    "id": "3807"
  }
}

Use the monitor ID to update or delete the monitor.

Update

Update a metric monitor by ID:

shell

curl https://api2.uptrace.dev/internal/v1/projects/<project_id>/monitors/<monitor_id> \
  --request PUT \
  --header "Authorization: Bearer <user_token>" \
  --header "Content-Type: application/json" \
  --data @monitor.json

The monitor.json file should contain the same JSON fields used to create the monitor.

Response

json

{
  "monitor": {
    "id": "3807"
  }
}

Delete

Delete a metric monitor by ID:

shell

curl https://api2.uptrace.dev/internal/v1/projects/<project_id>/monitors/<monitor_id> \
  --request DELETE \
  --header "Authorization: Bearer <user_token>"

Error Monitors

Create

Request

Create an error monitor:

shell

curl https://api2.uptrace.dev/internal/v1/projects/<project_id>/monitors \
  --request POST \
  --header "Authorization: Bearer <user_token>" \
  --header "Content-Type: application/json" \
  --data @monitor.json

Example monitor.json content:

json

{
  "name": "Number of spans per minute",
  "type": "error",
  "notifyEveryoneByEmail": true,
  "teamIds": [123],
  "channelIds": [123],
  "repeatInterval": { "strategy": "default" },
  "params": {
    "metrics": [{ "name": "uptrace_tracing_logs", "alias": "$logs" }],
    "query": "group by _group_id | where _system in ('log:error', 'log:fatal')"
  }
}

Supported JSON fields:

Field	Type	Required	Description
`key`	String	No	Unique string to deduplicate monitors
`name`	String	Yes	Monitor name
`type`	String	Yes	Must be `error`
`notifyEveryoneByEmail`	Boolean	No	Whether to notify everyone by email
`teamIds`	Array of integers	No	List of team IDs to notify by email (overrides `notifyEveryoneByEmail`)
`channelIds`	Array of integers	No	List of channel IDs for notifications
`params`	Object	Yes	Error monitor parameters (see below)

Error monitor parameters:

Parameter	Type	Required	Description
`metrics`	Array	Yes	Metrics to monitor, e.g., `[{"name": "uptrace_tracing_logs", "alias": "$logs"}]`
`query`	String	Yes	Query expression, e.g., `where _system in ('log:error', 'log:fatal')`

Response

json

{
  "monitor": {
    "id": "3807"
  }
}

Use the monitor ID to update or delete the monitor.

Update

Update an error monitor by ID:

shell

curl https://api2.uptrace.dev/internal/v1/projects/<project_id>/monitors/<monitor_id> \
  --request PUT \
  --header "Authorization: Bearer <user_token>" \
  --header "Content-Type: application/json" \
  --data @monitor.json

The monitor.json file should contain the same JSON fields used to create the monitor.

Response

json

{
  "monitor": {
    "id": "3807"
  }
}

Delete

Delete an error monitor by ID:

shell

curl https://api2.uptrace.dev/internal/v1/projects/<project_id>/monitors/<monitor_id> \
  --request DELETE \
  --header "Authorization: Bearer <user_token>"

Annotations API

See Annotations.

Grafana integrationBy adding Uptrace as a data source in Grafana, you can view traces and metrics stored by Uptrace in your favorite Grafana UI.

Data fixtures

Uptrace JSON API

Usage Limits

API Stability

Authentication

SSO

Spans API

List Spans

Query Groups

Alerting API

Metric Monitors

Create

Request

Response

Update

Response

Delete

Error Monitors

Create

Request

Response

Update

Response

Delete

Annotations API