On This Page

Home / StreamAI/StreamAI REST API

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-ai

For 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):

RequestMinimum 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 202 in v1. In v2, the status code reflects the result, such as 201 for a create. See Success Status Codes.
  • Response shape: In v1, every response wraps its result in an items array and a count. 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 the items and count format.
  • 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:

FieldDescription
statusAlways unverified. Workers don’t report listener readiness, so a successful response doesn’t mean that the gateway is ready to accept requests.
reasonWhy the status is unverified.
enforcementStatusapplied 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.
enforcementReasonWhy enforcementStatus has its value.
lookupVersionThe version of the published key snapshot, when publication succeeded.
targetWorkerCountThe number of connected StreamAI Workers. 0 when publication or Worker reporting is unavailable.
enforcedWorkerCountThe 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.

OperationRequest
List client keysGET /system/ai-gateway/client-keys
Create a client keyPOST /system/ai-gateway/client-keys
Get a client keyGET /system/ai-gateway/client-keys/{id}
Update a client keyPATCH /system/ai-gateway/client-keys/{id}
Revoke a client keyPOST /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:

FieldDescription
idThe unique ID of the key.
nameThe name of the key.
descriptionThe description, if the key has one.
tagsThe tags, if the key has any.
keyPrefixA non-secret prefix of the key, which you can use to identify it.
enabledWhether the key is enabled in the stored metadata. This field doesn’t confirm that the gateway enforces the key’s state.
createdAtWhen the key was created, in Unix milliseconds.
expiresAtWhen the key expires, in Unix milliseconds.
revokedAtWhen 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 v1API v2
Omit limit and offsetReturns all keys.Returns the first page, using the default page size.
Send offset without limitReturns a page of 100 keys.Returns a page that starts at offset, using the default page size.
Send limit without offsetReturns 400.Returns a page that starts at 0.
limit above the maximumNot 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:

PropertyDescription
nameRequired. The name of the key, 1 to 128 characters.
descriptionOptional. A description, up to 4,096 characters.
tagsOptional. An array of up to 100 unique tags. Each tag is 1 to 128 characters and can’t be blank.
expiresAtOptional. 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.
  • tags replaces the existing array. To remove a single tag, send the array without it.
  • A value of null removes 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 ​

OperationRequest
Get rolling 24-hour usageGET /system/ai-gateway/usage/day
Get daily usage historyGET /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:

ParameterDescription
fieldsOptional. 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.
keyIdOptional. 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.
windowOptional. 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 ​

CounterDescription
requestsThe number of requests.
errorsThe 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_inputThe number of input tokens.
tokens_outputThe number of output tokens.
tokens_cache_readThe number of cache-read tokens.
tokens_cache_writeThe number of cache-write tokens.
tokens_totalThe 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.
costThe estimated cost at list price, as an integer in micro-USD (one millionth of a US dollar).
unpriced_requestsThe 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:

FieldDescription
bucketSecondsThe width of each bucket in seconds. 600 for the rolling 24-hour view, and 86400 for the daily history.
startThe start of the first bucket, as an ISO 8601 UTC timestamp.
endThe end of the window, as an ISO 8601 UTC timestamp. The end is exclusive.
fieldsThe counters that each entry in points reports, in the order that each entry lists them.
totalThe 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.
keysOne entry for each client key that recorded usage in the window.
partialThe 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:

FieldDescription
idThe ID of the key, or __overflow or __nokey for the two special rows.
nameThe name of the key. null for a deleted key and for the special rows.
stateThe state of the key when StreamAI built the response: active, revoked, disabled, expired, or deleted. The special rows have the state sentinel.
tagsThe current tags of the key. An empty array for an untagged key, a deleted key, and the special rows.
pointsThe usage counters, one entry for each bucket that recorded usage.
latencyThe 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 points is an array of whole numbers. The first number is the zero-based bucket index. The remaining numbers are the values of the counters in fields, in the same order.
  • Each entry in latency is [bucketIndex, durationMsSum, durationCount]. To calculate the mean request duration of a bucket, divide durationMsSum by durationCount.

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:

ParameterDescription
fieldsOptional. The counters to report. It works as it does for the rolling 24-hour view.
keyIdOptional. The ID of a client key to report. It works as it does for the rolling 24-hour view.
startOptional. 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.
endOptional. 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 ​

StatusMeaning
400The 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.
403You 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.
404The request targets a Worker Group other than the StreamAI Worker Group.
503The 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.

OperationRequest
Get the settingsGET /system/ai-gateway/settings
Update the settingsPATCH /system/ai-gateway/settings

The settings have these properties:

PropertyDescription
traceReceiverUrlThe base URL of the receiver, or null when trace export is disabled.
sampleRateThe 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 http or https URL 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 ​

OperationAPI v1API v2
Any GET request200200
Create a client key202201, with a Location header for the new key
Update a client key200200
Revoke a client key202200
Update the trace export settings202200

Error Status Codes ​

StatusMeaning
400The request failed validation, or the body is malformed.
403You don’t have the required role on the StreamAI Worker Group, or, for the usage endpoints, an administrator role. See Permissions.
404The request targets a Worker Group other than the StreamAI Worker Group, or the key doesn’t exist.
409The request conflicts with the current state. For example, the active key limit is reached.
503StreamAI 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.