> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.v2.rasen.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.v2.rasen.ai/_mcp/server.

# Read quantity usage

GET https://api.v2.rasen.ai/v1/usage

Separate from request counts and billing. UTC [start,end), maximum 93 days. ID-list filters use repeated query names. Raw supplied ID count across fields is at most 100. Cursor binds normalized filters; filtered lists are not exact batch retrieval. Supports repeated agents and calls. Filter facts before aggregation. group_by=agent adds agent identity and group_by=call adds call identity; omission combines them. No cost/invoice amounts. For more than 100 ID values or call grouping, use POST /usage/query.

Reference: https://docs.v2.rasen.ai/api-reference/usage/list

## Authentication

- `Authorization` header (bearer token, required) — Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.

## Request

### Query parameters

- `limit` (integer, optional, default: 50) — Page size; 50 by default, at most 200.
- `cursor` (string, optional) — Opaque cursor bound to the workspace, every filter, grouping and limit. Send them unchanged with it. Expires after 24 hours.
- `start` (datetime, optional) — Inclusive UTC timestamp. Range must be at most 93 days.
- `end` (datetime, optional) — Exclusive UTC timestamp. Default range is trailing 30 days.
- `component` (list of string, optional) — Exact metering component filter, such as telephony or stt. Component vocabulary is open; unsupported filters return 400 rather than silently returning all data. Repeat for OR within this field; AND with other fields. These are not ID entries; at most 32 values per field, the same bound as the POST form. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.
- `call_id` (list of string, optional) — Repeat the query name for multiple IDs. OR within this field; AND across fields. Maximum 100 raw ID entries total across all ID filters. Blank values are invalid. Unknown/inaccessible IDs produce no rows, not an existence disclosure. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.
- `agent_id` (list of string, optional) — Repeat the query name for multiple IDs. OR within this field; AND across fields. Maximum 100 raw ID entries total across all ID filters. Blank values are invalid. Unknown/inaccessible IDs produce no rows, not an existence disclosure. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.
- `group_by` (list of enum, optional) — Repeat for several groupings. Omitted combines matching facts by component and unit. agent adds agent_id; call adds call_id. No other dimensions. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.
  - Allowed values: `agent`, `call`

## Response

### 200

Read quantity usage.

- `state` (string, required) — Open response vocabulary. Preserve unknown values; never assume they mean success.
- `items` (list of UsageItem, required)
- `next_cursor` (string, required, nullable)
- `range` (UsagePageRange, required) — The resolved UTC [start, end) range used, including defaults (trailing 30 days ending now).

## Errors

### 400 Bad Request Error

Invalid input or cursor. Correct the request.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 401 Unauthorized Error

Invalid, expired or revoked API key. Creator departure or membership changes do not invalidate a workspace key.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 403 Forbidden Error

Operation not allowed by current credential or workspace access.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 429 Too Many Requests Error

Rate limited. Respect Retry-After and retry the same intent where permitted.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 500 Internal Server Error

Internal error. The effect may have happened. Retry the same request with the same Idempotency-Key; read the resource before creating a new intent. For an operation that takes an Idempotency-Key, a client retry with the same key is safe: the server replays the stored outcome if the first attempt took effect; if the first attempt had no effect, the retry performs the operation once. Never retry with a new key.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 503 Service Unavailable Error

Service unavailable. Respect Retry-After where present. For an operation that takes an Idempotency-Key, a client retry with the same key is safe: the server replays the stored outcome if the first attempt took effect; if the first attempt had no effect, the retry performs the operation once. Never retry with a new key.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

## Types

### UsageItem

One row per group (component, unit and any requested grouping) for the whole resolved range. Different units never sum. A granularity option may be added later as an optional input.

- `component` (string, required) — Open component vocabulary, for example telephony or stt.
- `unit` (string, required) — Open unit vocabulary; never infer a price.
- `quantity` (double, required)
- `started_at` (datetime, required) — Equals UsagePage.range.start. No time buckets in this version.
- `ended_at` (datetime, required) — Equals UsagePage.range.end.
- `agent_id` (string, required, nullable) — Present agent identity when group_by=agent; null for ungrouped facts or unassigned usage.
- `call_id` (string, required, nullable) — Present when grouped by call; otherwise null.
- `events` (integer, required) — Number of metered facts combined into this row.

### UsagePageRange

The resolved UTC [start, end) range used, including defaults (trailing 30 days ending now).

- `start` (datetime, required)
- `end` (datetime, required)

### ErrorResponseError

Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

- `code` (string, required) — Stable code. Branch on code (and details.reason for conflict), never on message. Each code has one HTTP status; see components.x-error-catalog.
- `message` (string, required) — Safe description; no provider payload or submitted secrets.
- `details` (map from string to any, optional) — Safe code-specific details. The public fields for each code are listed in components.x-error-catalog. Details never contain a request fingerprint, a hash of a request, secret material or another tenant's data. forbidden may include required_capabilities (a list).
- `request_id` (string, optional) — Same value as the X-Request-Id header. Quote it to support.
- `retry` (string, optional) — Retry class of this code: no (fix the request or state first), yes (retry the same request and the same Idempotency-Key), retry_after (wait for Retry-After, then retry the same request). Open response vocabulary. Preserve unknown values; never assume they mean success.

## Examples

**Response**

```json
{
  "state": "measured",
  "items": [
    {
      "component": "telephony",
      "unit": "seconds",
      "quantity": 5412,
      "started_at": "2026-09-01T00:00:00Z",
      "ended_at": "2026-09-25T00:00:00Z",
      "agent_id": "agent_01j00000000000000000000000",
      "call_id": null,
      "events": 37
    }
  ],
  "next_cursor": null,
  "range": {
    "start": "2026-09-01T00:00:00Z",
    "end": "2026-09-25T00:00:00Z"
  }
}
```

**SDK Code**

```python usage_list_example
import requests

url = "https://api.v2.rasen.ai/v1/usage"

querystring = {"end":"2026-09-25T00:00:00Z","start":"2026-09-01T00:00:00Z"}

headers = {"Authorization": "Bearer <api_key>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript usage_list_example
const url = 'https://api.v2.rasen.ai/v1/usage?end=2026-09-25T00%3A00%3A00Z&start=2026-09-01T00%3A00%3A00Z';
const options = {method: 'GET', headers: {Authorization: 'Bearer <api_key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```ruby usage_list_example
require 'uri'
require 'net/http'

url = URI("https://api.v2.rasen.ai/v1/usage?end=2026-09-25T00%3A00%3A00Z&start=2026-09-01T00%3A00%3A00Z")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body
```

```java usage_list_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.v2.rasen.ai/v1/usage?end=2026-09-25T00%3A00%3A00Z&start=2026-09-01T00%3A00%3A00Z")
  .header("Authorization", "Bearer <api_key>")
  .asString();
```

```php usage_list_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.v2.rasen.ai/v1/usage?end=2026-09-25T00%3A00%3A00Z&start=2026-09-01T00%3A00%3A00Z', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
```

```csharp usage_list_example
using RestSharp;

var client = new RestClient("https://api.v2.rasen.ai/v1/usage?end=2026-09-25T00%3A00%3A00Z&start=2026-09-01T00%3A00%3A00Z");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);
```

```swift usage_list_example
import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.v2.rasen.ai/v1/usage?end=2026-09-25T00%3A00%3A00Z&start=2026-09-01T00%3A00%3A00Z")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```