---
title: "Get plan limits and current usage"
method: GET
path: "/api/v1/workspaces/{workspace_id}/limits"
tags: ["📊 Limits & Usage"]
---

# Get plan limits and current usage

`GET /api/v1/workspaces/{workspace_id}/limits`

## Request

- Base URL: `https://api.contentstudio.io`
- URL: `https://api.contentstudio.io/api/v1/workspaces/{workspace_id}/limits`
- Auth: API key in header `X-API-Key`

Read every metered entitlement for a workspace with what has been used, what the plan allows, and whether it applies — the same figures the billing screen shows for the same workspace. Addons and stackable multipliers are already folded into each limit, so the numbers are the customer's real entitlement rather than their base plan. Read it before a large batch instead of discovering a limit mid-run. The request-rate ceiling is not included — it is published on every response as the standard X-RateLimit-Limit and X-RateLimit-Remaining headers.

## Path parameters

- `workspace_id` string, required

## Response `200`

Limits and usage retrieved

- WorkspaceLimitsResponse
  - `status` boolean
  - `message` string
  - `data` object
    - `plan` object: Which plan produced these entitlements.
      - `slug` string
      - `name` string
      - `is_annually` boolean: True only when the plan bills yearly; false for monthly and quarterly.
      - `billing_cycle` 'monthly' | 'quarterly' | 'annually': How often the plan bills.
    - `limits` UsageLimitEntry[]
      - `key` 'workspaces' | 'social_accounts' | 'team_members' | 'x_posting_credits' | 'listening_topics' | 'listening_mentions' | 'ai_text_credits' | 'ai_image_credits' | 'ai_video_credits' | 'video_clip_credits' | 'ai_auto_reply_credits' | 'automations' | 'media_storage' | 'api_credits'
      - `label` string: Localised display name, matching the wording used in the product.
      - `used` integer: Bytes for `media_storage`, a count for everything else — `note` says which.
      - `limit` integer, nullable: Null when the entitlement is unlimited, in which case `note` says so.
      - `remaining` integer, nullable: Null whenever `limit` is. Never negative: usage can exceed a limit after a downgrade, in which case this is 0.
      - `scope` 'workspace' | 'account': What `used` counts. `workspace` is this workspace alone; `account` is every workspace the account owner has. Account-wide: workspaces, social_accounts, team_members, listening_topics, automations, media_storage. The credit counters are per-workspace.
      - `is_unlimited` boolean: True when the plan grants this without a ceiling; `limit` and `remaining` are then null.
      - `is_on_plan` boolean: False when the plan does not carry this at all — distinct from a fully consumed allowance, which `limit: null` alone cannot express.
      - `unit` 'count' | 'bytes': `bytes` for media_storage, `count` for everything else.
      - `period` 'monthly' | 'lifetime': `monthly` for credits that clear with the billing cycle, `lifetime` for running totals.
      - `resets_at` string, date-time, nullable: ISO 8601 instant the counter next clears. Null when `period` is `lifetime`.
      - `note` string: The state of this allowance in words.
    - `usage_reset` object: Periodic counters (AI credits, API calls, mentions, X posting) are cleared together on the 1st of each month, UTC, for every workspace — not on a per-customer billing anniversary.
      - `last_reset_at` string, date-time, nullable: When the counters were last cleared. Null on a workspace the job has not yet touched, which is why `next_reset_at` is derived from the schedule rather than from this.
      - `next_reset_at` string, date-time: When they next clear: 00:00 UTC on the 1st of next month.
      - `note` string, nullable

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.
- `404`: Workspace not found
- `429`: Too Many Requests - Rate limit exceeded

## Changes

- **2026-10-01** `2b5e04313216`: 1 info
  - added the optional property `data/plan/billing_cycle` to the response with the `200` status
- **2026-09-22** `ad0b687289a3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/changes/api/v1/workspaces/:workspace_id/limits/get.md)

---

[API](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1.md) - [All operations](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/revisions/2ce09d50369c?raw)