---
title: "Get Workflow Usage"
method: GET
path: "/api/v1/usage/workflows/{sheet_id}"
tags: ["Usage"]
---

# Get Workflow Usage

`GET /api/v1/usage/workflows/{sheet_id}`

## Request

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

Returns one sheet's usage in the requested window: totals, a per-day trend, the actions that spent the credits, the most frequent errors, the 20 most recent runs, and per-member spend. Defaults to the current calendar month (UTC).

`sheet_id` is one SHEET's id, as returned by List Workflow Usage — the same id the workflow endpoints take as `{sheet_id}`. Passing a workflow's main-sheet id reports that sheet alone, not the workflow's other sheets; for a workflow total, sum its rows in List Workflow Usage. An id that is not a UUID is a 400, so a 404 always means the window holds no usage for that sheet.

A key restricted by `allowed_workflow_ids` may only drill into sheets of the workflows on its list; the list endpoints are not filtered that way, because a filtered list would not add up to its own totals.

**What the key can see.** A key holding `org:read` (admin only) reports every member's runs and populates `per_user`. Any other key reports only the runs of the member who created it and leaves `per_user` empty — so a sheet only a colleague ran returns 404 for that key, even though the sheet exists.

| `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.

## Path parameters

- `sheet_id` string, uuid, required

## Query parameters

- `from` string
- `to` string

## Response `200`

Default Response

- object
  - `status` integer, required
  - `data` UsageWorkflowDetail, required: One sheet's usage in the window, broken down by day, action, error, run, and member.
    - `summary` object, required
      - `sheet_id` string, required
      - `name` string, required
      - `deleted` boolean, required
      - `shortcut_name` unknown, required
      - `total_runs` integer, required
      - `credits_consumed` number, required
      - `success_rate` number, required: Percentage, 0-100.
      - `cache_hit_rate` number, required: Percentage, 0-100.
    - `daily` UsageDailyItem[], required
      - `date` string, required: The day, `YYYY-MM-DD` in UTC.
      - `runs` integer, required: Action runs that day.
      - `credits` number, required: Credits consumed that day. May be fractional.
      - `cache_hits` integer, required: Runs served from cache that day. These cost no credits and are included in `runs`.
    - `top_actions` UsageTopAction[], required
      - `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.
    - `top_errors` object[], required: The most frequent errors in the window.
      - `message` string, required
      - `count` integer, required
      - `last_seen` string, required: ISO 8601.
    - `recent_runs` object[], required: The 20 most recent runs.
      - `run_id` string, required: Opaque identifier for the run. Use as a key only; the format is not part of the contract.
      - `created_at` string, required: ISO 8601.
      - `action_name` unknown, required
      - `email` string, required: The member who ran it.
      - `credits` number, required
      - `status` unknown, required
      - `fulfillment_source` string, required: How the run was answered: `api_call`, `cache_hit`, `user_api_key`, or `force_consumed`.
    - `per_user` UsageTopUser[], required: Empty for a key that only sees its own usage.
      - `email` string, required
      - `runs` integer, required
      - `credits` number, required

## 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).
- `404`: Not Found — no usage for this sheet in the window, or it is not visible to this key.
- `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)