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

# Get Subscription

> Return subscription status, credits, and renewal dates for the authenticated key scope

Returns the core subscription attached to the authenticated key owner
(workspace owner for workspace keys, owner user for personal keys).

Use this endpoint to show customers:

* current tier and subscription status
* credits limit, credits used, and credits remaining
* next renewal period end (`renews_at`) and credits reset date

## Response

<ResponseField name="scope" type="string">
  Authenticated key scope: `workspace` or `personal`.
</ResponseField>

<ResponseField name="workspace_id" type="string | null">
  Workspace ID for workspace keys, otherwise `null`.
</ResponseField>

<ResponseField name="subscription" type="object">
  Active core subscription details.

  <Expandable title="Subscription Object">
    <ResponseField name="status" type="string">
      Subscription status (for example `active`, `canceled`).
    </ResponseField>

    <ResponseField name="tier" type="string">
      Tier resolved from `polar_product_id` (`small`, `medium`, `large`, etc.).
    </ResponseField>

    <ResponseField name="billing_interval" type="string">
      Billing cadence: `month` or `year`.
    </ResponseField>

    <ResponseField name="current_period_start" type="string">
      ISO timestamp for current billing period start.
    </ResponseField>

    <ResponseField name="current_period_end" type="string">
      ISO timestamp for current billing period end.
    </ResponseField>

    <ResponseField name="renews_at" type="string">
      Renewal timestamp (same as `current_period_end`).
    </ResponseField>

    <ResponseField name="credits" type="object">
      Credits usage summary.

      <Expandable title="Credits Object">
        <ResponseField name="limit" type="number">
          Monthly credits available for this subscription.
        </ResponseField>

        <ResponseField name="used_this_period" type="number">
          Credits consumed in the current period.
        </ResponseField>

        <ResponseField name="remaining" type="number">
          Credits currently available (`limit - used_this_period`).
        </ResponseField>

        <ResponseField name="reset_at" type="string | null">
          Planned credits reset timestamp.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://www.genviral.io/api/partner/v1/subscription \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Subscription retrieved",
    "data": {
      "scope": "workspace",
      "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac",
      "subscription": {
        "status": "active",
        "tier": "small",
        "billing_interval": "month",
        "current_period_start": "2026-02-01T00:00:00.000Z",
        "current_period_end": "2026-03-01T00:00:00.000Z",
        "renews_at": "2026-03-01T00:00:00.000Z",
        "canceled_at": null,
        "is_paused": false,
        "paused_until": null,
        "credits": {
          "limit": 500,
          "used_this_period": 123,
          "remaining": 377,
          "reset_at": "2026-03-01T00:00:00.000Z"
        }
      }
    }
  }
  ```
</ResponseExample>

## Error Responses

* `401` - authentication failed (missing/invalid/revoked token)
* `402 subscription_required` - active Creator/Professional/Business plan required
* `403 tier_not_allowed` - Scheduler tier cannot use Partner API
* `500 subscription_lookup_failed` - unexpected subscription lookup failure