---
title: "Licence-enforced consumption for an account"
method: GET
path: "/api/v1/accounts/{account_id}/consumed"
tags: ["usage"]
---

# Licence-enforced consumption for an account

`GET /api/v1/accounts/{account_id}/consumed`

## Request

- Base URL: `https://platform.unstructuredapp.io`
- URL: `https://platform.unstructuredapp.io/api/v1/accounts/{account_id}/consumed`
- Auth: none declared

Units an account consumed over a window: the number its licence allowance is enforced against, summed over every workspace of the account.

Authenticate with an API key of any workspace in the account, or a bearer token of a member with permission to read the account's billing information. Any other account answers 403.

Counted in whole UTC days. Days before the counter began (`counted_from`) count as zero. A window that ends after today answers 503 rather than a smaller number, and so does any failure to read the count: a 200 is never a stand-in for a count that could not be read.

`breakdown=day` adds `days`, the quantity for every UTC day in the window (at most 366 days), for charting; weeks and months roll up from it.

`split=strategy` adds `strategies`: the pages by processing strategy (`fast`, `hi_res`, `vlm`), with `other` for every other kind of page and `unattributed` for pages counted before the split began (`strategies_counted_from`) or asserted as an opening balance. The five always sum to the quantity they split. The split is informational: the licence counts every page as one, whatever its strategy.

Call this endpoint at most 15 times per minute for each authenticated identity.

## Path parameters

- `account_id` integer, required

## Query parameters

- `unit` string, required: Unit to count. Today only `pages`.
- `start` string, date-time, required: Start of the window, RFC 3339. Counted in whole UTC days: the day containing `start` counts in full.
- `end` string, date-time, required: End of the window, RFC 3339. Counted in whole UTC days: the day containing `end` counts in full, unless `end` is exactly midnight UTC, which ends the window with the previous day.
- `breakdown` 'day', nullable: `day` adds `days`: the quantity for every UTC day in the window, at most 366 days.
- `split` 'strategy', nullable: `strategy` adds `strategies` to the total, and to each of `days`: pages by processing strategy (`fast`, `hi_res`, `vlm`, `other`, `unattributed`), summing to the quantity they split. Informational: every page counts as one against the licence.

## Headers

- `unstructured-api-key` string, nullable

## Response `200`

Successful Response

- AccountConsumed
  - `account_id` integer, required: The account the quantity was counted for.
  - `unit` string, required: Unit of `quantity`. Today only `pages`.
  - `quantity` integer, required: Units consumed by every workspace of the account over the requested window, counted in whole UTC days as the `start` and `end` parameters describe.
  - `counted_from` string, date-time, required: When the counter began counting. Days before it count as zero: a rack's counter starts with its fresh database.
  - `counted_through` string, date-time, required: When the counter last recorded usage. Informational.
  - `source` string, required: Which counter produced the quantity.
  - `days` DayQuantity[], nullable: Only with `breakdown=day`: one entry for every UTC day in the window, ascending, days without usage as 0. The entries sum to `quantity`.
    - `utc_day` string, date, required: The UTC day, `YYYY-MM-DD`.
    - `quantity` integer, required: Units consumed by the account on that day.
    - `strategies` StrategyQuantity[], nullable: Only with `split=strategy`: that day's quantity by strategy.
      - `strategy` string, required: `fast`, `hi_res`, `vlm`, `other` (every other kind of page) or `unattributed` (pages the split has no record of).
      - `quantity` integer, required: Pages of that strategy.
  - `strategies` StrategyQuantity[], nullable: Only with `split=strategy`: `quantity` by strategy, always the five entries `fast`, `hi_res`, `vlm`, `other` and `unattributed`, in that order, summing to `quantity`. Informational: every page counts as one against the licence.
    - `strategy` string, required: `fast`, `hi_res`, `vlm`, `other` (every other kind of page) or `unattributed` (pages the split has no record of).
    - `quantity` integer, required: Pages of that strategy.
  - `strategies_counted_from` string, date-time, nullable: Only with `split=strategy`: from here on every counted page is in the split; pages before it may be `unattributed`. Left out if the split never started.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-21** `178d46b64967`: 4 info
  - added the new optional `query` request parameter `split`
  - added the optional property `days/anyOf[subschema #1]/items/strategies` to the response with the `200` status
  - added the optional property `strategies` to the response with the `200` status
  - added the optional property `strategies_counted_from` to the response with the `200` status
- **2026-10-16** `37954f8df5b3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unstructuredapp/apis/platform-api/changes/api/v1/accounts/:account_id/consumed/get.md)

---

[API](https://skmtc.dev/unstructuredapp/apis/platform-api.md) - [All operations](https://skmtc.dev/unstructuredapp/apis/platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unstructuredapp/apis/platform-api/revisions/94fb718d49fe?raw)