> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chowder.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Subscription

> Retrieve your organization's current subscription tier and usage.

Check what plan your organization is on and how many instances you're using. Useful for building billing dashboards or enforcing limits in your own application logic.

## Authorization

Requires an **organization-level** API key in the `Authorization` header.

## Response

<ResponseField name="tier" type="string">
  Your current subscription tier. One of `shrimp`, `crab`, `lobster`, or `whale`.
</ResponseField>

<ResponseField name="instance_limit" type="number | null">
  The maximum number of instances allowed on this tier. `null` means unlimited (whale tier — you're living large).
</ResponseField>

<ResponseField name="instance_count" type="number">
  How many instances your organization currently has.
</ResponseField>

<ResponseField name="stripe_customer_id" type="string | null">
  Your Stripe customer ID, if a billing relationship exists.
</ResponseField>

<ResponseField name="stripe_subscription_id" type="string | null">
  Your Stripe subscription ID, if you're on a paid plan.
</ResponseField>

<RequestExample>
  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl https://api.chowder.dev/v1/subscription \
    -H "Authorization: Bearer chd_sk_your_org_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "tier": "lobster",
    "instance_limit": 25,
    "instance_count": 12,
    "stripe_customer_id": "cus_abc123",
    "stripe_subscription_id": "sub_def456"
  }
  ```
</ResponseExample>