---
title: "Get Usage Overview"
method: GET
path: "/api/v1/usage/overview"
tags: ["Usage"]
---

# Get Usage Overview

`GET /api/v1/usage/overview`

## Request

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

Returns usage for the requested window: totals, a per-day trend, and the top workflows, actions and members by credits spent. Defaults to the current calendar month (UTC).

**What a run is.** One run is one action call against one row. A run served from cache is counted in `total_runs` and `cache_hits` but costs no credits; `cache_savings` reports what those runs would have cost.

`top_workflows` lists workflow sheets only. Source spend counts toward `summary` — which is the whole organization's usage — and is attributed by List Source Usage.

**What the key can see.** A key holding `org:read` (admin only) reports the whole organization and populates `top_users` and `summary.active_users`. Any other key reports only the usage of the member who created it, leaves `top_users` empty, and omits `active_users`.

| `code` | Status | Meaning |
|---|---|---|
| `LEDGER_CUTOVER_SPAN` | 400 | The window crosses the date this organization's usage history moved stores, and cannot be reported as one figure. 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` UsageOverview, required: Usage totals for the requested window, with the daily trend and the top consumers.
    - `summary` object, required
      - `total_runs` integer, required: Action runs in the window.
      - `credits_consumed` number, required: Credits spent in the window.
      - `success_rate` number, required: Percentage of runs that succeeded, 0-100.
      - `cache_savings` number, required: Credits NOT spent because a run was served from cache. Not part of `credits_consumed`.
      - `avg_cost_per_run` number, required: `credits_consumed / total_runs`.
      - `active_users` integer: Members who ran something. Omitted for a key that only sees its own usage.
    - `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_workflows` UsageTopWorkflow[], required
      - `sheet_id` string, required: UUID of the SHEET the runs happened on. Pass to `GET /api/v1/usage/workflows/{sheet_id}`, or look it up in List Workflow Usage for the workflow it belongs to.
      - `name` string, required
      - `deleted` boolean, required: True when the workflow has since been deleted. Its usage still counted, so it is still listed.
      - `shortcut_name` unknown, required
      - `runs` integer, required
      - `credits` number, required
    - `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_users` UsageTopUser[], required: Empty for a key that only sees its own usage.
      - `email` string, required
      - `runs` integer, required
      - `credits` number, required
    - `top_error` object, required: The most frequent error in the window, or null when nothing failed.
      - `message` string
      - `count` integer

## 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)