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

# Account API: Read the Subscription State of an API Key

> Check whether the account behind a Scrunch API key is on a trial, actively paying, or churned, and read its plan and current billing period.

## Overview

The Account API returns the subscription state of the account a Scrunch API key belongs to: the organization, its plan, and the current billing period.

Use it to gate a partner experience by trial state, drive an upgrade prompt in your own UI, or confirm the account is still paying before serving premium features.

The endpoint is read-only and does not change how the account is billed.

***

## When to use the Account API

Use the Account API when you need to:

* Tell a trial account from a paid or churned one inside a product-led growth flow
* Read the trial end date to schedule reminders or conversion prompts
* Confirm the account behind an API key is still active before serving a paid integration

For per-brand data such as visibility, prompts, or citations, use the [Query API](/api-reference/query/overview) or [Responses API](/api-reference/responses/overview) instead.

***

## Endpoint

| Method | Path       | Purpose                                                    |
| ------ | ---------- | ---------------------------------------------------------- |
| GET    | `/account` | Subscription state of the account this API key belongs to. |

The endpoint requires a bearer token with the `query` scope. See [Authentication](/getting-started/authentication).

The account is derived from the API key, so there are no path or query parameters. Session (JWT) callers return `400`, because a user may belong to several organizations and the credential alone does not name one.

***

## Example

```bash theme={null}
curl -X GET \
  "https://api.scrunchai.com/v1/account" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"
```

**Response:**

```json theme={null}
{
  "organization_id": "01M2GBYWVMXJ69VXZ2D5NFJJ6S",
  "organization_name": "Sitecore PLG Trial",
  "plan": "enterprise",
  "plan_display_name": "Enterprise",
  "status": "trialing",
  "current_period_start": "2026-09-21T00:00:00Z",
  "current_period_end": "2027-09-21T00:00:00Z"
}
```

***

## Reading the response

### `status`

`status` reports the account's subscription state. Most values mirror Stripe's own subscription statuses:

| Value                | Meaning                                                      |
| -------------------- | ------------------------------------------------------------ |
| `active`             | Paying customer in good standing.                            |
| `trialing`           | On a trial. `current_period_end` is the date the trial ends. |
| `past_due`           | Payment failed but Stripe is still retrying.                 |
| `unpaid`             | Stripe stopped retrying after failed payments.               |
| `paused`             | Subscription is paused.                                      |
| `incomplete`         | Initial payment has not succeeded yet.                       |
| `canceled`           | Subscription was canceled.                                   |
| `incomplete_expired` | Initial payment window elapsed without success.              |

Two values are specific to this endpoint:

* `subscription_not_found` — Scrunch holds no Stripe subscription record for this account. This is normal for manually invoiced accounts and CS-managed trials, and **is not a sign that the account lapsed**. Treat it as "active unless you know otherwise" in a gating flow.
* `unknown` — Scrunch cannot vouch for the account's current state, either because its billing record is no longer being kept up to date or because the subscription is in a state this endpoint does not publish yet. **Keep your current behavior rather than treating it as a lapse.**

### `current_period_end` for trials

While `status` is `trialing`, `current_period_end` is the date the trial ends. Use it to schedule reminders or drive an in-product conversion prompt.

### `plan` and `plan_display_name`

`plan` is the machine-readable plan name (for example `enterprise`); use it in gating logic. `plan_display_name` is the human-readable label (for example `Enterprise`); show it in UI. Both are empty strings when the account has no plan on file.

***

## Errors

| Status | Meaning                                                                                                                                   |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The credential is not scoped to a single account. Returned when the caller authenticates with a user session (JWT) instead of an API key. |
| `401`  | Missing or invalid bearer token.                                                                                                          |
| `403`  | The API key does not have the `query` scope.                                                                                              |
| `404`  | The account tied to this API key no longer exists.                                                                                        |


## Related topics

- [Get Account Status](/api-reference/account/get-account-status.md)
- [AXP Unpublish API: Take Optimized Pages Off the Edge](/api-reference/axp/unpublish.md)
- [Site Optimization API: Recommendations, by type and by page](/api-reference/site-optimization/overview.md)