> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intake usage

> Read how much each source took in, and one source hour by hour.

```http theme={null}
GET /api/v1/streams/usage
```

Returns what each source took in over a window, and how each stands against its budget. Requires `intake_usage.read`, or `sys.telemetry.read` in the `_sys` organization.

A figure that is not known is `null`, not zero. When the records cannot be read, `available` is `false` and every figure is `null`. When metering began inside the window, `complete` is `false` and the figures are lower bounds.

**Query parameters**

| Param | Default | Notes |
| - | - | - |
| `dimension` | `credential` | `credential`, `stream`, or `service`. |
| `window_secs` | 86400 | Length of the window, limited to 3600 through 2678400. It starts on the hour. |

`source_key` reads `<credential_kind>:<id>` for a credential (`api_token`, `connector`, `user`, `internal`) and `<stream_type>:<name>` for a stream. For a service it is the name, with an empty string for events that name none and `*` for the services past the limit.

```bash cURL theme={null}
curl "http://localhost:5080/api/v1/streams/usage?dimension=credential&window_secs=86400" \
  -H "authorization: Bearer $MS_TOKEN"
```

```json 200 theme={null}
{
  "generated_at_micros": 1790000000000000,
  "window_start_micros": 1789912800000000,
  "window_end_micros": 1790000000000000,
  "window_secs": 86400,
  "dimension": "credential",
  "available": true,
  "metering_started_at_micros": 1785000000000000,
  "total_bytes": 21474836480,
  "total_events": 15000000,
  "truncated": false,
  "sources": [
    {
      "source_key": "api_token:3KE0ot1NtfCTJ3V3XxBNbqx9Y62",
      "label": {
        "kind": "api_token",
        "subkind": "personal",
        "name": "checkout-prod",
        "detail": "ms_1a2b3c4d5e6f7a8b",
        "missing": false
      },
      "budgetable": true,
      "intake_bytes": 21474836480,
      "events": 15000000,
      "complete": true,
      "share": 1.0,
      "budget": {
        "id": "3KE0p2QvLdXw9mB7sYcT1uZaH4n",
        "dimension": "credential",
        "source_key": "api_token:3KE0ot1NtfCTJ3V3XxBNbqx9Y62",
        "period": "day",
        "limit_size": 10240,
        "warn_percent": 80,
        "notify_user_ids": ["3KE0mZ8rHq2Nf6Vt4Kd1XbLwP7s"],
        "updated_at_micros": 1789900000000000,
        "period_start_micros": 1789948800000000,
        "used_bytes": 21474836480,
        "used_complete": true,
        "used_ratio": 2.0,
        "state": "exceeded"
      }
    }
  ]
}
```

## One source

```http theme={null}
GET /api/v1/streams/usage/detail
```

Returns one source over the window: its totals, its hours gathered into buckets, and how it divides along the other two dimensions, at most 20 sources each.

| Param | Default | Notes |
| - | - | - |
| `dimension` | Required | `credential`, `stream`, or `service`. |
| `source_key` | Required | The source, as `GET /api/v1/streams/usage` gives it. |
| `window_secs` | 86400 | Limited to 3600 through 2678400. |
| `bucket_count` | 24 | Buckets in the series, limited to 6 through 48. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.