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

# Get user plan

> Get the subscription plan of one of your users

This endpoint returns the subscription plan of one of your users: a plan you gave them with [Update user plan](/api-reference/white-label/update-user-plan), or one they subscribed to on your platform. `data` is `null` when the user has no plan.

<Note>
  This endpoint is available to the **account owner** (with an active plan) and to team members with **Billing Access**. Other users receive a 403 Forbidden error. Only users of your platform can be read: any other ID, including the owner account, returns 404.
</Note>

### Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the user. Administrators can list user IDs with [Get platform users](/api-reference/white-label/get-users).
</ParamField>

### Response

<ResponseField name="data" type="object | null">
  The user's plan, or `null` when they have none

  <Expandable title="data properties">
    <ResponseField name="plan_id" type="integer">
      The plan's ID, as in [List plans](/api-reference/white-label/list-plans)
    </ResponseField>

    <ResponseField name="name" type="string">
      The plan's name
    </ResponseField>

    <ResponseField name="source" type="string">
      `manual` when you gave the plan, `trial` for a trial the user started on your platform, or `paid` for a subscription the user pays on your platform. Only `manual` plans can be changed or removed through the API
    </ResponseField>

    <ResponseField name="billing" type="string">
      `monthly` or `yearly`
    </ResponseField>

    <ResponseField name="included_minutes" type="number">
      The minutes included in the plan every month
    </ResponseField>

    <ResponseField name="included_credits" type="integer">
      The chat credits included in the plan every month
    </ResponseField>

    <ResponseField name="minutes_renew_at" type="string | null">
      When the user's plan minutes are renewed next, in ISO 8601
    </ResponseField>

    <ResponseField name="ends_at" type="string | null">
      When the plan ends, in ISO 8601, or `null` when it has no end date
    </ResponseField>

    <ResponseField name="minutes" type="string | null">
      For plans you gave: `none`, `monthly` or `yearly`, as set with [Update user plan](/api-reference/white-label/update-user-plan#minutes). `null` for plans the user subscribed to on your platform
    </ResponseField>

    <ResponseField name="when_short" type="string | null">
      For plans you gave: `auto_top_up` or `wait`, what happens when the owner's balance cannot cover a renewal. `null` for plans the user subscribed to on your platform
    </ResponseField>

    <ResponseField name="renewal" type="object | null">
      For plans you gave, the state of the monthly renewal. `null` for plans the user subscribed to on your platform

      <Expandable title="renewal properties">
        <ResponseField name="status" type="string">
          `ok` when the next renewal is planned, `pending` when its day has come and the owner's balance could not cover it yet, or `none` for plans without minutes and for plans that end before their next renewal
        </ResponseField>

        <ResponseField name="next_at" type="string | null">
          The day of the next renewal, or of the pending one, in ISO 8601
        </ResponseField>

        <ResponseField name="missing_minutes" type="number">
          While `pending`, how many minutes the owner's balance is missing; `0` means the renewal runs within the hour. Always `0` otherwise
        </ResponseField>

        <ResponseField name="last_renewed_at" type="string | null">
          When the plan was last renewed, in ISO 8601, or `null` before its first renewal
        </ResponseField>

        <ResponseField name="prepaid_minutes" type="number | null">
          For yearly minutes, the plan minutes still prepaid for the coming months. `null` otherwise
        </ResponseField>

        <ResponseField name="prepaid_until" type="string | null">
          For yearly minutes, when the prepaid 12 months end, in ISO 8601. `null` otherwise
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Plan Given theme={null}
  {
    "data": {
      "plan_id": 6,
      "name": "Agency",
      "source": "manual",
      "billing": "yearly",
      "included_minutes": 500,
      "included_credits": 900,
      "minutes_renew_at": "2026-11-02T14:25:38+00:00",
      "ends_at": null,
      "minutes": "yearly",
      "when_short": "auto_top_up",
      "renewal": {
        "status": "ok",
        "next_at": "2026-11-02T14:25:38+00:00",
        "missing_minutes": 0,
        "last_renewed_at": null,
        "prepaid_minutes": 5500,
        "prepaid_until": "2027-10-02T14:25:38+00:00"
      }
    }
  }
  ```

  ```json 200 Renewal Pending theme={null}
  {
    "data": {
      "plan_id": 5,
      "name": "Starter",
      "source": "manual",
      "billing": "monthly",
      "included_minutes": 100,
      "included_credits": 0,
      "minutes_renew_at": "2026-10-02T14:25:38+00:00",
      "ends_at": "2026-12-31T23:59:59+00:00",
      "minutes": "monthly",
      "when_short": "wait",
      "renewal": {
        "status": "pending",
        "next_at": "2026-10-02T14:25:38+00:00",
        "missing_minutes": 11.17,
        "last_renewed_at": "2026-09-02T14:25:40+00:00",
        "prepaid_minutes": null,
        "prepaid_until": null
      }
    }
  }
  ```

  ```json 200 Subscribed on the Platform theme={null}
  {
    "data": {
      "plan_id": 5,
      "name": "Starter",
      "source": "paid",
      "billing": "monthly",
      "included_minutes": 100,
      "included_credits": 0,
      "minutes_renew_at": "2026-10-30T14:25:38+00:00",
      "ends_at": null,
      "minutes": null,
      "when_short": null,
      "renewal": null
    }
  }
  ```

  ```json 200 No Plan theme={null}
  {
    "data": null
  }
  ```

  ```json 401 Unauthenticated theme={null}
  {
    "message": "Unauthenticated."
  }
  ```

  ```json 403 Not Administrator theme={null}
  {
    "message": "You are not an administrator."
  }
  ```

  ```json 403 No Billing Access theme={null}
  {
    "message": "You do not have access to these settings."
  }
  ```

  ```json 404 User Not Found theme={null}
  {
    "message": "User not found."
  }
  ```

  ```json 429 Too Many Requests theme={null}
  {
    "message": "Too Many Attempts."
  }
  ```
</ResponseExample>

### Rate limit

The platform settings, default limits, user settings and plan endpoints share a limit of 60 requests per minute for each account. Above it they return `429`, and the `Retry-After` response header tells you how many seconds to wait.

### Example

```bash theme={null}
curl -X GET https://app.autocalls.ai/api/white-label/users/123/plan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.