StreamAI REST API
Use the Cribl REST API to manage your StreamAI client keys, check gateway status, read usage, and configure trace export. For the full list of request and response properties, see the API Reference.
These endpoints are the management API for your StreamAI gateway.
Call the API
Availability
The StreamAI management API is available only in commercial Cribl.Cloud Workspaces that have StreamAI enabled. For details, see Availability.
Base URL
StreamAI management endpoints are scoped to the StreamAI Worker Group, which has the ID stream-ai. Every path on this page is relative to this base URL:
https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/stream-aiFor example, the full URL to list client keys is https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/stream-ai/system/ai-gateway/client-keys.
A request that targets any other Worker Group returns a 404 error. For more information about base URLs, see Base URLs.
Authentication
Include a Bearer token in the Authorization header of each request. To learn how to get a token, see Authenticate with the Cribl API.
Permissions
Most management endpoints require a role on the StreamAI Worker Group (stream-ai):
| Request | Minimum Worker Group role |
|---|---|
GET requests: gateway status, client keys, usage, and the trace export settings. | Read Only |
| Requests that change state: creating, updating, and revoking client keys, and updating the trace export settings. | Editor or Admin |
The Editor and Admin roles include read access, so one of them covers both changing and viewing StreamAI resources. A request without the required role returns 403.
The usage endpoints also require an administrator role: Organization Admin, Organization Owner, Workspace Admin, or Workspace Owner. A caller without one of these roles gets 403 from the usage endpoints, even with a Worker Group role that allows reading. Provisioning and deleting the AI Gateway with the /products/stream-ai endpoint require one of the same roles. See Get Started with StreamAI.
API Versions
The StreamAI endpoints support API v1 and API v2. The versions differ in the following ways.
- Success status codes: Most operations that change state return
202in v1. In v2, the status code reflects the result, such as201for a create. See Success Status Codes. - Response shape: In v1, every response wraps its result in an
itemsarray and acount. This includes a response that returns a single object, such as the gateway status, a single client key, or the trace export settings. In v2, a response that returns a single object is the object itself. Only the list of client keys keeps theitemsandcountformat. - Pagination: See List Client Keys.
To select a version, send the x-cribl-api-version header with the value 1 or 2. Without the header, the endpoints use API v1. A value above 2 on a versioned API path returns 404.
Get Gateway Status
GET /system/ai-gateway
Reports whether the latest client keys were published to the AI Gateway Workers. The response has these fields:
| Field | Description |
|---|---|
status | Always unverified. Workers don’t report listener readiness, so a successful response doesn’t mean that the gateway is ready to accept requests. |
reason | Why the status is unverified. |
enforcementStatus | applied when every connected StreamAI Worker reports that it holds the current key snapshot. pending otherwise, including when no Worker is connected. The response to a change, such as creating a key, is always pending, because the change hasn’t reached a Worker yet. |
enforcementReason | Why enforcementStatus has its value. |
lookupVersion | The version of the published key snapshot, when publication succeeded. |
targetWorkerCount | The number of connected StreamAI Workers. 0 when publication or Worker reporting is unavailable. |
enforcedWorkerCount | The number of connected StreamAI Workers that report holding the current snapshot. 0 when publication or Worker reporting is unavailable. |
After you create or revoke a key, poll this endpoint until enforcementStatus is applied, and set a timeout. A key usually reaches the Workers in 10 to 30 seconds, and a Worker can take about 1 more second to load the snapshot that it reports.
Client Keys
A client key is the credential that a client application uses to send requests to the gateway.
| Operation | Request |
|---|---|
| List client keys | GET /system/ai-gateway/client-keys |
| Create a client key | POST /system/ai-gateway/client-keys |
| Get a client key | GET /system/ai-gateway/client-keys/{id} |
| Update a client key | PATCH /system/ai-gateway/client-keys/{id} |
| Revoke a client key | POST /system/ai-gateway/client-keys/{id}/revoke |
There is no DELETE endpoint for client keys. Revoking a key is the only way to end its lifecycle.
Responses never include a key’s secret value, except in the response to the create request. Responses describe a key with these fields:
| Field | Description |
|---|---|
id | The unique ID of the key. |
name | The name of the key. |
description | The description, if the key has one. |
tags | The tags, if the key has any. |
keyPrefix | A non-secret prefix of the key, which you can use to identify it. |
enabled | Whether the key is enabled in the stored metadata. This field doesn’t confirm that the gateway enforces the key’s state. |
createdAt | When the key was created, in Unix milliseconds. |
expiresAt | When the key expires, in Unix milliseconds. |
revokedAt | When the key was revoked, in Unix milliseconds. Present only on a revoked key. |
List Client Keys
GET /system/ai-gateway/client-keys
Returns key metadata in creation order, including revoked and expired keys. StreamAI keeps the metadata of a revoked or expired key for 90 days after the key was revoked or expired. It also keeps at most 1,000 revoked and expired keys, and removes the oldest first. The response never includes the key values.
Pagination depends on the API version:
| API v1 | API v2 | |
|---|---|---|
Omit limit and offset | Returns all keys. | Returns the first page, using the default page size. |
Send offset without limit | Returns a page of 100 keys. | Returns a page that starts at offset, using the default page size. |
Send limit without offset | Returns 400. | Returns a page that starts at 0. |
limit above the maximum | Not applicable. | StreamAI reduces limit to the maximum page size. |
By default, the v2 page size is 100 and the maximum is 1000. A limit of 0 or no limit uses the default. A negative limit or offset, or a blank limit or offset, returns 400.
Create a Client Key
POST /system/ai-gateway/client-keys
Creates a key and returns its secret value. The response is the only time that StreamAI returns the secret value. Store it securely, because you can’t retrieve it again. If you lose the value, revoke the key and create a new one.
The request body supports these properties:
| Property | Description |
|---|---|
name | Required. The name of the key, 1 to 128 characters. |
description | Optional. A description, up to 4,096 characters. |
tags | Optional. An array of up to 100 unique tags. Each tag is 1 to 128 characters and can’t be blank. |
expiresAt | Optional. When the key expires, as Unix time in milliseconds. The value must be in the future and no more than 365 days from now. A value outside that range returns 400. If you omit it, the key expires 30 days after creation. |
curl --request POST \
--url "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/stream-ai/system/ai-gateway/client-keys" \
--header "Authorization: Bearer ${token}" \
--header "Content-Type: application/json" \
--data '{
"name": "my-app",
"description": "Key for the platform team",
"tags": ["platform", "team-a"]
}'The response includes the metadata fields in Client Keys, plus a key field with the secret value. In API v1, the response has status 202 and wraps these fields in items, so the secret value is items[0].key. In API v2, the response has status 201 and the key field is a top-level property. See API Versions. The response also includes the fields that report publication state: enforcementStatus, enforcementReason, and lookupVersion.
If your Workspace has reached the limit of active keys, the request returns 409. The limit is 1,000 active keys, and it counts keys that aren’t revoked, disabled, or expired. Revoke or let expire a key you no longer need, then try again.
Get a Client Key
GET /system/ai-gateway/client-keys/{id}
Returns the metadata of one key. A key that doesn’t exist returns 404.
Update a Client Key
PATCH /system/ai-gateway/client-keys/{id}
Updates the key’s description and tags. These are the only properties that you can change. You can’t change a key’s secret value or expiration with this request.
- Properties that you omit stay as they are.
tagsreplaces the existing array. To remove a single tag, send the array without it.- A value of
nullremoves the property.
The validation rules for description and tags are the same as for creating a key. Any other property in the request body returns 400.
Revoke a Client Key
POST /system/ai-gateway/client-keys/{id}/revoke
Disables a key permanently. You can’t undo a revocation. Revoking a key that’s already revoked succeeds and keeps the original revokedAt time. The response includes the revoked key’s metadata and its publication state.
Read Usage
| Operation | Request |
|---|---|
| Get rolling 24-hour usage | GET /system/ai-gateway/usage/day |
| Get daily usage history | GET /system/ai-gateway/usage/history |
The usage endpoints require an administrator role and at least the Read Only role on the StreamAI Worker Group. For details, see Permissions. They report what the StreamAI Workers recorded. They aren’t a billing record.
The rolling 24-hour view reads the current window from in-memory metrics on the Leader. The previous window and the daily history read System Insights, so they depend on how long System Insights keeps data. See Usage History and System Insights Retention.
GET /system/ai-gateway/usage/limits always returns 503 with the message AI Gateway consumption ledger is unavailable, because StreamAI has no consumption ledger.
Get Rolling 24-Hour Usage
GET /system/ai-gateway/usage/day
Returns usage for 24 hours as 144 buckets of 10 minutes each, broken down by client key. The response includes request latency. By default, the window is the last 24 hours. The request supports these query parameters:
| Parameter | Description |
|---|---|
fields | Optional. The counters to report. Repeat the parameter to request several. If you omit it, the response reports every counter. See Usage counters. An unknown counter returns 400. |
keyId | Optional. The ID of a client key to report. Repeat the parameter to request up to 100 keys. If you omit it, the response includes every key that recorded usage, including the __overflow and __nokey rows. More than 100 values returns 400. |
window | Optional. Which 24 hours to report. current (the default) is the last 24 hours, ending with the bucket in progress. previous is the 24 hours before the current window, and all of its buckets are complete, so the response has no partial list. Send the parameter at most once. An unknown or repeated value returns 400. |
The usage views report usage by client key only. A request with a model parameter returns 400.
The previous window reads System Insights. See Usage History and System Insights Retention.
curl --request GET \
--url "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/stream-ai/system/ai-gateway/usage/day?fields=requests&fields=tokens_total&keyId=<key-id>" \
--header "Authorization: Bearer ${token}"Usage Counters
| Counter | Description |
|---|---|
requests | The number of requests. |
errors | The number of requests that failed. A request fails if the client disconnected before the response finished, the response status isn’t 2xx, or the provider reported a failure in a 2xx response. |
tokens_input | The number of input tokens. |
tokens_output | The number of output tokens. |
tokens_cache_read | The number of cache-read tokens. |
tokens_cache_write | The number of cache-write tokens. |
tokens_total | The total token count. It’s the provider’s reported total or, when the provider reports none, the sum of the reported token counts. Per-key token limits use this counter, but StreamAI doesn’t enforce per-key limits. |
cost | The estimated cost at list price, as an integer in micro-USD (one millionth of a US dollar). |
unpriced_requests | The number of requests that reported tokens but have no cost. While this counter is above 0, cost is a lower bound. See How StreamAI Estimates Cost. |
The cost counter is an estimate at list price, not a bill. StreamAI calculates it from the token counts that the provider reported and the list price of the model that answered. For a cribl/auto request, that’s the model that answered, which can differ from the alias in the request.
A request that StreamAI can’t price adds nothing to cost. For example, StreamAI has no price for the model, or the provider reported no tokens. The cost of a bucket can therefore be lower than the actual spend. The unpriced_requests counter shows how many requests StreamAI couldn’t price.
StreamAI records the cache counters only when the provider reports cache usage. StreamAI doesn’t count a counter that the provider doesn’t report, and the usage response shows such a counter as 0. For requests to /v1/messages, the cache tokens are in addition to the input tokens. For the OpenAI endpoints, the cache tokens are part of the input tokens that StreamAI already counts.
Usage Response
The usage endpoints share one response format. In API v1, the response object is the only entry in the items array, and count is 1. These fields describe the response object:
| Field | Description |
|---|---|
bucketSeconds | The width of each bucket in seconds. 600 for the rolling 24-hour view, and 86400 for the daily history. |
start | The start of the first bucket, as an ISO 8601 UTC timestamp. |
end | The end of the window, as an ISO 8601 UTC timestamp. The end is exclusive. |
fields | The counters that each entry in points reports, in the order that each entry lists them. |
total | The sum of the entries in keys, including the __overflow and __nokey rows. This is the Workspace total unless the request filters by keyId. It has the points field, and the latency field in the rolling 24-hour view. |
keys | One entry for each client key that recorded usage in the window. |
partial | The indexes of buckets whose data is incomplete. In the current rolling 24-hour window, the bucket in progress is always listed, which is the last bucket, index 143. In the daily history, today’s bucket is listed while the day is still running. The field is absent when every bucket is complete, as in the previous window. |
Each entry in keys has these fields:
| Field | Description |
|---|---|
id | The ID of the key, or __overflow or __nokey for the two special rows. |
name | The name of the key. null for a deleted key and for the special rows. |
state | The state of the key when StreamAI built the response: active, revoked, disabled, expired, or deleted. The special rows have the state sentinel. |
tags | The current tags of the key. An empty array for an untagged key, a deleted key, and the special rows. |
points | The usage counters, one entry for each bucket that recorded usage. |
latency | The request durations, one entry for each bucket that recorded requests. The daily history doesn’t report this field. |
The __overflow row holds requests that a Worker could no longer attribute to a key, because it reached its limit on tracked keys. The __nokey row is normally empty. A request without a client key gets a 401 before StreamAI records usage, so the row holds only a usage record that has an empty key ID. A deleted key is a key that StreamAI removed after it counted the key’s usage.
The points and latency arrays are sparse, so buckets with no usage are omitted:
- Each entry in
pointsis an array of whole numbers. The first number is the zero-based bucket index. The remaining numbers are the values of the counters infields, in the same order. - Each entry in
latencyis[bucketIndex, durationMsSum, durationCount]. To calculate the mean request duration of a bucket, dividedurationMsSumbydurationCount.
To convert a bucket index into a time, add the index multiplied by bucketSeconds to start.
Get Daily Usage History
GET /system/ai-gateway/usage/history
Returns usage as daily buckets over whole UTC calendar days, broken down by client key. The response has the same format as the rolling 24-hour view, with bucketSeconds set to 86400. It doesn’t report latency. The request supports these query parameters:
| Parameter | Description |
|---|---|
fields | Optional. The counters to report. It works as it does for the rolling 24-hour view. |
keyId | Optional. The ID of a client key to report. It works as it does for the rolling 24-hour view. |
start | Optional. The first UTC calendar day to report, inclusive, as YYYY-MM-DD. It can be no earlier than 34 days before today, so that a range spans at most 35 days, counting today. If you omit it, the range starts 29 days before today. |
end | Optional. The last UTC calendar day to report, inclusive, as YYYY-MM-DD. It can be no later than today, and no earlier than start. If you omit it, the range ends today. |
A start more than 34 days before today returns 400, with a message such as start must not be earlier than 2026-10-01, 34 days before today. A request with a model parameter also returns 400.
curl --request GET \
--url "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/stream-ai/system/ai-gateway/usage/history?start=2026-11-01&end=2026-11-04&fields=requests&fields=cost" \
--header "Authorization: Bearer ${token}"Usage History and System Insights Retention
The daily history, and the previous window of the rolling 24-hour view, read System Insights. System Insights keeps data for 2 days by default. The history accepts a range of up to 35 days, but with the default retention, days older than the retention period report no usage. They aren’t an error, and the response omits their buckets. To read a longer history, a Workspace needs a System Insights retention that covers the range.
If System Insights isn’t enabled, doesn’t answer within 5 seconds, or returns data that StreamAI can’t read, the request returns 503 with the message AI Gateway usage history is unavailable. StreamAI never answers with an empty response in these cases, because an empty response would read as no usage.
In Cribl.Cloud, the Overview page links to the System Insights tab of your Workspace’s details page when the retention is too short. You can’t change the retention through the Workspace’s REST API: the endpoint that sets it requires a Cribl operator permission.
Usage Status Codes
| Status | Meaning |
|---|---|
400 | The request failed validation. For example, fields includes an unknown counter, keyId has more than 100 values, or window has an unknown value or is repeated. Other causes are a malformed date in start or end, an inverted range, an end later than today, a start more than 34 days before today, and a model parameter. |
403 | You don’t have an administrator role, or you don’t have at least the Read Only role on the StreamAI Worker Group. The administrator roles are Organization Admin, Organization Owner, Workspace Admin, and Workspace Owner. |
404 | The request targets a Worker Group other than the StreamAI Worker Group. |
503 | The usage metrics store is unavailable (AI Gateway usage metrics are unavailable), or, for the previous window and the daily history, the usage history store is unavailable (AI Gateway usage history is unavailable). For usage/limits, the consumption ledger is unavailable. Try the request again later. |
Manage Trace Export Settings
The trace export settings hold the base URL of the Cribl OpenTelemetry Source that receives completed inference traces, and the fraction of inferences to capture. StreamAI exports each completed inference as one OpenTelemetry (OTLP) span. For the span’s name and attributes, see Export Inference Traces.
You can also set the receiver URL in the UI. On the Overview page, select Connect AI Observability and enter the destination URL from the AI Observability App. See View Usage on the Overview Page.
| Operation | Request |
|---|---|
| Get the settings | GET /system/ai-gateway/settings |
| Update the settings | PATCH /system/ai-gateway/settings |
The settings have these properties:
| Property | Description |
|---|---|
traceReceiverUrl | The base URL of the receiver, or null when trace export is disabled. |
sampleRate | The fraction of inferences to capture, as a number from 0 to 1. For example, 0.25 captures about one in four inferences. The default is 1, which captures every inference. GET returns this property only while a receiver is configured. |
GET returns the settings as StreamAI stored them. In API v1, GET and PATCH wrap the settings in items and count, as described in API Versions. PATCH replaces the settings, so the request body must include traceReceiverUrl. Send a URL to configure or replace the receiver. Send null to disable trace export. If you omit sampleRate, StreamAI captures every inference, so include it on each request that must keep a lower rate. A sampleRate outside the range of 0 to 1, any other property, or an empty body returns 400.
The URL must meet these requirements:
- It’s an absolute
httporhttpsURL with a host. - It’s no longer than 2,048 characters.
- It doesn’t include credentials, a query string, or a fragment.
- In Cribl.Cloud, the hostname resolves to a publicly routable address.
The URL is the base URL of the receiver. Don’t include the /v1/traces signal path. StreamAI appends it, and sends the spans in OTLP protobuf format over HTTP.
StreamAI normalizes the URL before it stores it, for example by removing trailing slashes, so the response can differ slightly from what you sent. It doesn’t test whether the receiver is reachable, because the receiver might be reachable only from the Worker network.
A successful update confirms that StreamAI stored the value and started a deployment to the StreamAI Worker Group. The update doesn’t confirm that every Worker already applies the setting. If StreamAI can’t store the value or can’t start the deployment, the request returns 503. When the deployment fails to start, the new value might already be stored.
curl --request PATCH \
--url "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/stream-ai/system/ai-gateway/settings" \
--header "Authorization: Bearer ${token}" \
--header "Content-Type: application/json" \
--data '{
"traceReceiverUrl": "https://otel.example.com",
"sampleRate": 0.25
}'Enabling trace export sends the content of each inference, including prompts and responses, to the receiver. For details, see Export Inference Traces.
Response Status Codes
Success Status Codes
| Operation | API v1 | API v2 |
|---|---|---|
Any GET request | 200 | 200 |
| Create a client key | 202 | 201, with a Location header for the new key |
| Update a client key | 200 | 200 |
| Revoke a client key | 202 | 200 |
| Update the trace export settings | 202 | 200 |
Error Status Codes
| Status | Meaning |
|---|---|
400 | The request failed validation, or the body is malformed. |
403 | You don’t have the required role on the StreamAI Worker Group, or, for the usage endpoints, an administrator role. See Permissions. |
404 | The request targets a Worker Group other than the StreamAI Worker Group, or the key doesn’t exist. |
409 | The request conflicts with the current state. For example, the active key limit is reached. |
503 | StreamAI can’t reach the storage for keys, the usage metrics store, or the trace export settings, or can’t start their deployment. Try the request again later. |
API Reference
For the properties of each request and response, see the Cribl Stream API Reference.