Query Request Usage

Returns the actual usage of a single request — token counts and cost — identified by its request ID (the X-Request-Id response header value, prefixed with REQ-). Useful for reconciling the real billing of a single call once it completes, e.g. asynchronous video generation tasks.

A request that failed over between providers produces multiple ledger entries: failed attempts are voided (status is upstream_failed, cost 0) and the final successful one is billed. All entries are returned, ordered by creation time ascending.

Authentication

Put the API key in the request header:

Authorization: Bearer sk_live_YOUR_API_KEY

API

GET/api/business/v1/customer/request-usage

Get actual usage for a single request

Return the ledgers (tokens + cost) produced by one gateway request, identified by the request_id query parameter (the X-Request-Id response header value, REQ-...). Fields match the dashboard ledger view. A request that failed over between providers produces multiple ledgers (voided attempts + the final billed one). API key only.

Bearer API KeyUse the Authorization: Bearer sk_live_... header; x-api-key is also supported.

Request structure

The section below confirms the method, URL and authentication scheme. It is an HTTP structure snippet, not a standalone runnable example.

HTTP

GET https://www.silvamux.com/api/business/v1/customer/request-usage
Authorization: Bearer $SILVAMUX_API_KEY

Request parameters

Parameter	Type & location	Required	Description
`Authorization`	string · header	Yes	Bearer API Key (sk_live_...)
`X-Organization-Id`	string · header	No	Not required for API key auth
`request_id`	string · query	Yes	Request ID from the X-Request-Id response header (REQ-...)

Response

`200`OK

application/json · CustomerRequestUsageResponse

Field	Type	Required	Description
`$schema`	string (uri)	No	A URL to the JSON Schema for this object.
`ledgers`	array<CustomerRequestUsageEntry>	Yes	Ledgers produced by this request, ordered by created_at asc
`ledgers.cost_points`	string	Yes	Cost in points after discount
`ledgers.created_at`	string (date-time)	Yes	Ledger creation time (RFC3339)
`ledgers.first_token_latency_ms`	integer (int64)	Yes	Time to first token in ms (streamed requests; 0 = unrecorded)
`ledgers.generated_artifacts`	integer (int64)	Yes	Generated artifact count (video/image async tasks)
`ledgers.is_stream`	boolean	Yes	Whether the request was streamed
`ledgers.original_cost`	string	Yes	Cost in points before discount
`ledgers.project_name`	string	Yes	Project name
`ledgers.request_model`	string	Yes	Model name as supplied in the request
`ledgers.status`	string	Yes	Ledger status (billed / upstream_failed / pending)
`ledgers.tokens`	RequestTokens	Yes	—
`ledgers.tokens.billable_prompt_tokens`	integer (int64)	Yes	Billable prompt tokens (prompt + cache creation)
`ledgers.tokens.cached_tokens`	integer (int64)	Yes	Cache-read prompt tokens
`ledgers.tokens.completion_tokens`	integer (int64)	Yes	Completion tokens
`ledgers.tokens.prompt_tokens`	integer (int64)	Yes	Prompt tokens (uncached)
`ledgers.tokens.total_tokens`	integer (int64)	Yes	Total tokens
`ledgers.total_latency_ms`	integer (int64)	Yes	Total request latency in ms (0 = unrecorded)
`request_id`	string	Yes	Gateway request ID (X-Request-Id response header)

`default`Error

application/problem+json · ErrorModel

Field	Type	Required	Description
`$schema`	string (uri)	No	A URL to the JSON Schema for this object.
`detail`	string	No	A human-readable explanation specific to this occurrence of the problem.
`errors`	array<ErrorDetail>	No	Optional list of individual error details
`errors.location`	string	No	Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
`errors.message`	string	No	Error message text
`errors.value`	any	No	The value at the given location
`instance`	string (uri)	No	A URI reference that identifies the specific occurrence of the problem.
`status`	integer (int64)	No	HTTP status code
`title`	string	No	A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
`type`	string (uri)	No	A URI reference to human-readable documentation for the error.；Default: about:blank

Parameters

request_id: required, the X-Request-Id response header value (REQ- prefixed).
Only requests belonging to the API key's organization can be queried; anything else returns 404.

Examples

curl "https://www.silvamux.com/api/business/v1/customer/request-usage?request_id=REQ-01M2JBYGGVY77KPRWNZFDFTWZR" \
  -H "Authorization: Bearer $SILVAMUX_API_KEY"

# pip install requests
import os
import requests

resp = requests.get(
    "https://www.silvamux.com/api/business/v1/customer/request-usage",
    params={"request_id": "REQ-01M2JBYGGVY77KPRWNZFDFTWZR"},
    headers={"Authorization": f"Bearer {os.environ['SILVAMUX_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json()["ledgers"])

// Node 18+ (built-in fetch)
const requestId = "REQ-01M2JBYGGVY77KPRWNZFDFTWZR";
const query = new URLSearchParams({ request_id: requestId });

const resp = await fetch(
  `https://www.silvamux.com/api/business/v1/customer/request-usage?${query}`,
  {
    headers: { Authorization: `Bearer ${process.env.SILVAMUX_API_KEY}` },
  },
);

const data = await resp.json();
console.log(data.ledgers);

// Standard library only
package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    url := "https://www.silvamux.com/api/business/v1/customer/request-usage?request_id=REQ-01M2JBYGGVY77KPRWNZFDFTWZR"

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer "+os.Getenv("SILVAMUX_API_KEY"))

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Response:

{
  "request_id": "REQ-01M2JBYGGVY77KPRWNZFDFTWZR",
  "ledgers": [
    {
      "request_model": "deepseek-v4-pro",
      "project_name": "Default Project",
      "status": "billed",
      "tokens": {
        "prompt_tokens": 85,
        "cached_tokens": 0,
        "billable_prompt_tokens": 85,
        "completion_tokens": 10,
        "total_tokens": 95
      },
      "generated_artifacts": 0,
      "is_stream": false,
      "first_token_latency_ms": 0,
      "total_latency_ms": 1358,
      "original_cost": "0.001035",
      "cost_points": "0.001035",
      "created_at": "2026-09-15T11:06:32.861800Z"
    }
  ]
}

Field	Description
`request_id`	The queried request ID
`ledgers`	All ledger entries produced by this request, ordered by creation time ascending
`ledgers[].request_model`	The model name as supplied in the request
`ledgers[].status`	`billed` / `upstream_failed` (voided, cost 0) / `pending`
`ledgers[].tokens`	Token usage breakdown
`ledgers[].generated_artifacts`	Artifact count for async tasks (video/image)
`ledgers[].original_cost`	Cost before discount
`ledgers[].cost_points`	Actual charged cost after discount

Error Handling

HTTP	Code	Description
401	`INVALID_TOKEN`	API key missing or invalid
404	`REQUEST_USAGE_NOT_FOUND`	Request ID not found, or not owned by the API key's organization
422	—	`request_id` parameter missing