---
title: "Get plan and usage"
method: GET
path: "/v1/usage"
tags: ["Workspace"]
---

# Get plan and usage

`GET /v1/usage`

## Request

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

The plan in force (including a trial), every limit, and this month's usage: runs against the allowance, sources, API keys, seats and stored evidence. Use it before creating sources or queueing runs to avoid a 402 plan_limit.

## Headers

- `X-Request-Id` string
- `SourceFinch-Project` string, uuid

## Response `200`

Plan and usage

- Usage: The workspace's plan, trial, limits and this month's usage: check before creating sources or queueing runs.
  - `plan` string, required: The plan in force now (during a trial, the trial plan)
  - `subscription` object, required
    - `tier` string, required
    - `status` string, nullable, required
    - `current_period_end` string, nullable, required: ISO-8601 timestamp (UTC)
    - `cancel_at_period_end` boolean, required
  - `trial` object, nullable, required
    - `plan` string, required
    - `started_at` string, required: ISO-8601 timestamp (UTC)
    - `ends_at` string, required: ISO-8601 timestamp (UTC)
    - `ended_at` string, nullable, required: ISO-8601 timestamp (UTC)
    - `outcome` string, nullable, required
  - `retention_grace_until` string, nullable, required: After a downgrade, over-limit items stay paused (not deleted) until then
  - `runs` object, required
    - `used` integer, required
    - `allowance` integer, required: Monthly runs in the plan plus run packs bought this month
    - `packs` integer, required
    - `soft_overage` boolean, required
    - `scheduled_ceiling` integer, required
    - `manual_ceiling` integer, required
  - `sources` UsageMeter, required: Current use against the plan's limit
    - `used` integer, required
    - `limit` integer, nullable, required: null: unlimited
  - `api_keys` UsageMeter, required: Current use against the plan's limit
    - `used` integer, required
    - `limit` integer, nullable, required: null: unlimited
  - `seats` UsageMeter, required: Current use against the plan's limit
    - `used` integer, required
    - `limit` integer, nullable, required: null: unlimited
  - `storage_bytes` UsageMeter, required: Current use against the plan's limit
    - `used` integer, required
    - `limit` integer, nullable, required: null: unlimited
  - `limits` object, required: Every limit of the plan in force (schedule floor, retention days, browser mode, origins per day, …)
  - `upgrade_url` string, required

## Other responses

- `401`: Problem details; `code` is `unauthenticated`
- `403`: Problem details; `code` is `forbidden`
- `429`: Problem details; `code` is `rate_limited`
- `500`: Problem details; `code` is `internal`

---

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