---
title: "List Source Usage"
method: GET
path: "/api/v1/usage/sources"
tags: ["Usage"]
---

# List Source Usage

`GET /api/v1/usage/sources`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/usage/sources`
- Auth: HTTP bearer

Returns credits spent per source instance in the requested window, ranked by credits. Defaults to the current calendar month (UTC).

`source_instance_id` is the same id `GET /api/v1/sources` returns under that name — the source INSTANCE, not the `source_id` source-type slug. Pass it to `GET /api/v1/sources/{source_instance_id}/data` to see what the spend produced.

Source runs are reported here and excluded from List Workflow Usage, so the two never double-count.

Not paginated, and capped at 100 rows — but that cap is applied to workflow sheets and sources together before they are split, so an organization whose highest spenders are all sheets can see fewer than 100 sources here, or none at all. Narrow the window to bring sources into the top 100.

**What the key can see.** A key holding `org:read` (admin only) reports the whole organization. Any other key reports only the usage of the member who created it.

| `code` | Status | Meaning |
|---|---|---|
| `LEDGER_CUTOVER_SPAN` | 400 | The window crosses the date this organization's usage history moved stores. Request the window on one side of `cutover_at`. |

Requires the `billing:read` scope, which every role holds.

## Query parameters

- `from` string
- `to` string

## Response `200`

Default Response

- object
  - `status` integer, required
  - `data` UsageSourceRow[], required: One row per source with activity in the window, highest spend first.
    - `source_instance_id` string, required: The source INSTANCE id, as listed by `GET /api/v1/sources`. Not the source-type slug.
    - `name` string, required
    - `deleted` boolean, required: True when the source has since been deleted.
    - `runs` integer, required
    - `credits` number, required
    - `success_count` integer, required
    - `cache_hits` integer, required
    - `cache_hit_rate` number, required: Percentage of runs served from cache, 0-100.
    - `top_actions` UsageTopAction[], required: The three actions that spent the most credits on this source.
      - `action_name` string, required: Display name of the action, e.g. `Find Email`. Falls back to the internal slug when unmapped.
      - `runs` integer, required
      - `credits` number, required
      - `cache_hits` integer: How many of `runs` were served from cache.

## Other responses

- `400`: Bad Request — `from` or `to` is not a parsable ISO 8601 date, `from` is later than `to`, or the window crosses the usage ledger cutover.
- `401`: Unauthorized — missing or invalid API key
- `403`: Forbidden. `code` says which permission refused: ROLE_FORBIDDEN (your role), INSUFFICIENT_SCOPE (the API key's scopes), WORKFLOW_FORBIDDEN (no access to the workflow), KEY_WORKFLOW_FORBIDDEN (the API key's workflow restriction).
- `429`: Too Many Requests — rate limit exceeded. Check `Retry-After` header for seconds until the limit resets.

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)