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

# List Workflow Usage

`GET /api/v1/usage/workflows`

## Request

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

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

**One row is one SHEET, not one workflow.** A workflow with three sheets produces three rows sharing a `workflow_id`; sum them for the workflow total. Names match the Sheet schema — `sheet_id` is the row, `workflow_id` is the workflow it belongs to — so either can be passed straight to the workflow endpoints. `is_main_sheet` marks the workflow's own main sheet, whose `sheet_id` equals its `workflow_id`.

Capped at the 100 highest-spending sheets, and not paginated. Narrow the window to see further down.

Sources are reported separately by List Source Usage, not here.

Deleted workflows still appear with `deleted: true` — their runs really did spend credits in the window, so dropping them would under-report the total.

**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, so a sheet a colleague ran is absent.

| `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` UsageWorkflowRow[], required: One row per sheet with activity in the window, highest spend first.
    - `sheet_id` string, required: UUID of the sheet. Pass to Get Workflow Usage, and as `{sheet_id}` on every sheet-scoped workflow endpoint. Runs of a global catalog shortcut are listed under their run's own id, named after the shortcut; only the usage endpoints accept that id.
    - `name` string, required: Fully qualified name, `Parent > Sheet` for a child sheet.
    - `deleted` boolean, required: True when the workflow has since been deleted.
    - `workflow_id` string, required: UUID of the parent workflow this sheet belongs to — the `{workflow_id}` of the workflow endpoints. Equals `sheet_id` on a main sheet.
    - `workflow_name` string, required: The parent workflow's name.
    - `sheet_name` string, required: This sheet's own label — `Main Sheet` for an unnamed main sheet — without the parent prefix.
    - `shortcut_name` unknown, required
    - `is_main_sheet` boolean, required
    - `runs` integer, required
    - `credits` number, required
    - `success_count` integer, required: Runs that succeeded.
    - `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 in this sheet.
      - `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)