---
title: "Get a project's subscription state"
method: GET
path: "/v1/subscription"
tags: ["Billing"]
---

# Get a project's subscription state

`GET /v1/subscription`

## Request

- Base URL: `https://serp-agent.com`
- URL: `https://serp-agent.com/v1/subscription`
- Auth: HTTP bearer

Billing state of one project, derived from the same fields the access gate reads. `status`: `active` (live paid month — work endpoints are all-inclusive), `pending_payment` (an API-created checkout is in flight, <24h old), or `none`. `plan` is `basic`/`pro` when resolvable (manual-tier marker or live Creem lookup), else null. Sandbox projects always report `none` (they run on the free trial budget).

## Query parameters

- `project_id` string, required

## Response `200`

The project's subscription state.

- SubscriptionStatus
  - `project_id` string, required
  - `plan` 'basic' | 'pro' | 'null', nullable, required: Null when no subscription or the tier cannot be resolved.
  - `status` 'active' | 'pending_payment' | 'none', required: active = live paid month (work endpoints all-inclusive); pending_payment = API checkout in flight; none = no subscription (pay per unit with credits, or subscribe).
  - `paid_until` string, date-time: Present when active.
  - `sandbox` boolean: Present (true) on sandbox projects — they run on the free trial budget, no subscription.
  - `note` string

## Other responses

- `400`: Missing project_id. Code: `invalid_request`.
- `401`: Missing, malformed, unknown, revoked, or expired API key. Codes: `unauthorized`, `key_revoked`, `key_expired`.
- `404`: No such project on this account. Code: `not_found`.
- `429`: Rate limit exceeded (600 requests/minute per API key). Honor `Retry-After`.

---

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