---
title: "Read what the account has spent"
method: GET
path: "/usage"
tags: ["Usage"]
---

# Read what the account has spent

`GET /usage`

## Request

- Base URL: `https://api.epovest.com/v1`
- URL: `https://api.epovest.com/v1/usage`
- Auth: HTTP bearer

`GET /credits` says what is left to spend; this says what has been spent, and on what: the
ledger entries, plus the same amounts by month, by cost line, by project and by tracker. The
amounts outside `by_month` are a cumulative total over `period`, never a monthly figure, so
quote the period alongside the amount. `this_month_forecast` is the month in progress: report
it as a forecast, never as spend.

## Query parameters

- `month` string
- `type` 'in' | 'out'
- `page` integer
- `per_page` integer

## Response `200`

The spend of the period.

- Usage
  - `currency` string, required
  - `month` string, nullable, required: The month asked for, as `YYYY-MM`.
  - `period` object, required: The first and last check debit counted, so quote it alongside the amount.
    - `from` string, date, nullable
    - `to` string, date, nullable
  - `this_month_forecast` object, required: The month in progress: `total_minor` is `spent_minor` (already debited) plus `remaining_minor` (what the active trackers and monitored corroborations will still run before month end, counted as real occurrences and recomputed from their configuration). A forecast: report it as one.
    - `month` string
    - `total_minor` integer
    - `spent_minor` integer
    - `remaining_minor` integer
    - `lines` SpendLine[]
      - `category` 'survey' | 'ai_analyst' | 'competitor_scan' | 'corroboration_check' | 'other': The cost line: `survey`, `ai_analyst` (the supplement of the AI analysts grafted onto a check), `competitor_scan`, `corroboration_check`, and `other` for a line not named yet, which stays visible rather than dropping out of a total.
      - `amount_minor` integer
      - `count` integer
    - `active_trackers` integer
    - `monitored_corroborations` integer
  - `total_spent_minor` integer, required: The check spend of the period, matching the sum of both breakdowns.
  - `by_category` SpendLine[], required
    - `category` 'survey' | 'ai_analyst' | 'competitor_scan' | 'corroboration_check' | 'other': The cost line: `survey`, `ai_analyst` (the supplement of the AI analysts grafted onto a check), `competitor_scan`, `corroboration_check`, and `other` for a line not named yet, which stays visible rather than dropping out of a total.
    - `amount_minor` integer
    - `count` integer
  - `by_project` ProjectSpend[], required
    - `project_id` string, uuid, nullable: Null for the trackers filed under no project.
    - `name` string, nullable
    - `archived` boolean
    - `spent_minor` integer
    - `lines` SpendLine[]
      - `category` 'survey' | 'ai_analyst' | 'competitor_scan' | 'corroboration_check' | 'other': The cost line: `survey`, `ai_analyst` (the supplement of the AI analysts grafted onto a check), `competitor_scan`, `corroboration_check`, and `other` for a line not named yet, which stays visible rather than dropping out of a total.
      - `amount_minor` integer
      - `count` integer
  - `by_tracker` TrackerSpend[], required: The spend of each tracker over the period, biggest spender first.
    - `tracker_id` string, uuid, nullable: The current version of the chain, so it goes straight into `GET /trackers/{id}/scores`.
    - `name` string, nullable
    - `project_id` string, uuid, nullable
    - `listed` boolean: False for a tracker that is no longer in the account list; its spend still counts in the total.
    - `spent_minor` integer
    - `survey_count` integer
  - `by_month` object[], required: Per month, newest first, up to twelve.
    - `month` string
    - `spent_minor` integer
    - `by_category` SpendLine[]
      - `category` 'survey' | 'ai_analyst' | 'competitor_scan' | 'corroboration_check' | 'other': The cost line: `survey`, `ai_analyst` (the supplement of the AI analysts grafted onto a check), `competitor_scan`, `corroboration_check`, and `other` for a line not named yet, which stays visible rather than dropping out of a total.
      - `amount_minor` integer
      - `count` integer
    - `by_project` ProjectSpend[]
      - `project_id` string, uuid, nullable: Null for the trackers filed under no project.
      - `name` string, nullable
      - `archived` boolean
      - `spent_minor` integer
      - `lines` SpendLine[]
        - `category` 'survey' | 'ai_analyst' | 'competitor_scan' | 'corroboration_check' | 'other': The cost line: `survey`, `ai_analyst` (the supplement of the AI analysts grafted onto a check), `competitor_scan`, `corroboration_check`, and `other` for a line not named yet, which stays visible rather than dropping out of a total.
        - `amount_minor` integer
        - `count` integer
    - `by_tracker` TrackerSpend[]
      - `tracker_id` string, uuid, nullable: The current version of the chain, so it goes straight into `GET /trackers/{id}/scores`.
      - `name` string, nullable
      - `project_id` string, uuid, nullable
      - `listed` boolean: False for a tracker that is no longer in the account list; its spend still counts in the total.
      - `spent_minor` integer
      - `survey_count` integer
  - `months_total` integer, required: How many months have spend, so you can tell whether twelve covered everything.
  - `entries` object[], required: The ledger itself, newest first.
    - `kind` string
    - `category` 'survey' | 'ai_analyst' | 'competitor_scan' | 'corroboration_check' | 'other': The cost line: `survey`, `ai_analyst` (the supplement of the AI analysts grafted onto a check), `competitor_scan`, `corroboration_check`, and `other` for a line not named yet, which stays visible rather than dropping out of a total.
    - `amount_minor` integer: Signed.
    - `balance_after_minor` integer, nullable
    - `reason` string, nullable
    - `tracker_name` string, nullable
    - `period_start` string, date, nullable
    - `on_demand` boolean, nullable: Where a check debit came from: true when the check was asked for on the tracker, false when the cadence ran it, null on an entry that is not a check debit. The two are worth separating in a spend report: one is a decision, the other the schedule.
    - `invoice_id` string, nullable
    - `created_at` string, date-time: The instant the entry was posted, in RFC 3339 with the UTC offset, to the second and carrying the fraction the ledger recorded: it is the time that tells entries apart and orders them.
  - `pagination` Pagination, required
    - `page` integer, required
    - `per_page` integer, required
    - `total` integer, required
    - `pages` integer, required

## Other responses

- `401`: `unauthenticated`: missing, unknown or revoked key.
- `403`: `insufficient_scope`: the credential may not do this, either because the key lacks the scope, or, on a one-click connection, because the person lacks the role the action needs (manager, or owner to start, pause and top up). On that path, read it as "this person may not do this" and tell them which role the action needs.
- `429`: `rate_limited`: 120 requests per minute per credential, sliding window. Retry after `Retry-After` seconds.
- `503`: `service_unavailable`: a backend is unreachable; retry later.

---

[API](https://skmtc.dev/epovest/apis/epovest-api.md) · [All operations](https://skmtc.dev/epovest/apis/epovest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/epovest/apis/epovest-api/revisions/7a78ee27ecbb?raw)