---
title: "Get Billing Status"
method: GET
path: "/v1/billing/status"
tags: ["Billing"]
---

# Get Billing Status

`GET /v1/billing/status`

## Request

- Base URL: `https://api.pinbridge.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pinbridge.io/v1/billing/status`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Current plan, billing status and quota usage for the workspace.

`calls_used` counts the pins published successfully this month (calendar month,
UTC) against `quota_calls_monthly`, and `quota_reset_at` is when it resets.
Only successful new pins count, scheduled pins included when they publish;
reads, failures and retries don't. Once the quota is used up, credits are
spent one per pin if `credits_enabled`; with no quota or credits left,
publishing returns `402 quota_exceeded` (or `credits_exhausted`) while every
other endpoint keeps working.

It also reports usage against the other plan limits (Pinterest accounts, API
keys, weekly AI assistant requests) and, below the top self-serve plan, the
next plan up with its `upgrade_url`.

The `plan` value `pro` is the Agency plan (`plan_name`). Works with any API key
that has the read scope; a dashboard session needs a role that can manage billing.

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Response `200`

Successful Response

- BillingStatusResponse: Plan, billing status and quota usage for the current workspace.
  - `plan` 'free' | 'starter' | 'growth' | 'pro' | 'enterprise', required: Subscription plan tiers.
  - `billing_provider` string: `stripe` when billed through Stripe, `database` when the plan is set by PinBridge
  - `billing_cycle` 'monthly' | 'annual': Subscription billing frequency.
  - `billing_status` 'active' | 'trialing' | 'past_due' | 'canceled' | 'unpaid', required: Billing status from Stripe.
  - `trial_active` boolean: Whether a free trial is running
  - `trial_ends_at` string, date-time, nullable: Set while a trial is active
  - `current_period_start` string, date-time, nullable: Start of the current subscription period
  - `current_period_end` string, date-time, nullable: End of the current subscription period (next renewal)
  - `subscription_cancel_at` string, date-time, nullable: When a scheduled cancellation takes effect
  - `quota_calls_monthly` integer, required: Successful pin publishes included per month
  - `calls_used` integer, required: Pins published successfully this month (calendar month, UTC)
  - `quota_reset_at` string, date-time, nullable: When `calls_used` resets: the start of next month (UTC)
  - `credits_remaining` integer: Prepaid credits left, spent one per pin once the quota is used up
  - `credits_enabled` boolean: Whether this workspace spends credits after the quota
  - `credits_purchase_allowed` boolean: Whether this workspace can buy credit packs right now
  - `quota_exhausted` boolean: True when `calls_used` has reached `quota_calls_monthly`
  - `plan_consumption_percent` integer: `calls_used` as a percentage of the monthly quota, 0-100
  - `storage_quota_bytes` integer: Asset library storage limit
  - `storage_used_bytes` integer: Asset library storage in use
  - `storage_used_percent` integer: `storage_used_bytes` as a percentage of the storage limit
  - `storage_warning` string, nullable: `80`, `95` or `100` once storage use crosses that percentage
  - `pinterest_accounts_limit` integer, required: Connected Pinterest accounts allowed
  - `uploaded_media_assets` boolean, required: Whether the plan includes asset uploads
  - `bulk_imports` boolean, required: Whether the plan includes bulk JSON and CSV imports
  - `plan_name` string, nullable: The plan's display name, e.g. `Agency` for `pro`
  - `pinterest_accounts_used` integer: Connected Pinterest accounts in use
  - `api_keys_limit` integer, nullable: API keys allowed; null means unlimited
  - `api_keys_used` integer: Active API keys, not counting AI assistant connections
  - `assistant_requests_limit` integer: AI assistant (MCP) requests allowed per week; 0 means unlimited
  - `assistant_requests_used` integer: AI assistant (MCP) requests used this week
  - `assistant_requests_reset_at` string, date-time, nullable: When the weekly AI assistant request count resets
  - `recommended_plan` 'free' | 'starter' | 'growth' | 'pro' | 'enterprise': Subscription plan tiers.
  - `upgrade_url` string, nullable: Pricing page link highlighting `recommended_plan`, or null

## Other responses

- `422`: Validation Error

---

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