> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).
>
> To search these docs, send a `GET` request to `https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question>` with a URL-encoded question. No authentication needed. It returns a JSON array of `{content, source_url}`, most relevant first.

# GET /api-keys/{api_key_id}/rotations

**List API key rotations**

Returns a paginated list of rotations for an API key. Use the query parameters to page through results.

Authenticate using the rotatable API key you want to list rotations for — a key can only list its own rotations. Only API keys created as rotatable support this.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key_id` | string | required | Unique Paddle ID for this API key entity, prefixed with `apikey_`. (pattern: `^apikey_[a-z\d]{26}$`) |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | array | optional | Return only the IDs specified. Use a comma-separated list to get multiple entities. |
| `after` | string | optional | Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations. |
| `per_page` | integer | optional | Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.

Default: `50`; Maximum: `200`. (Max: 200; default: `50`) |

## Response (200)

- `data`: array (required)
  - `id`: string (required) — Unique Paddle ID for this API key rotation entity, prefixed with `apkrot_`. (pattern: `^apkrot_[a-z\d]{26}$`)
  - `api_key_id`: string (required) — Unique Paddle ID for this API key entity, prefixed with `apikey_`. (pattern: `^apikey_[a-z\d]{26}$`)
  - `new_key`: string (required) — The new API key secret created by this rotation.
  - `grace_period_seconds`: integer (required) — How long, in seconds, the old secret keeps working after the new secret is activated. The new secret is activated the first time it's used to authenticate a request. Set to `0` to stop the old secret working as soon as the new one is activated. (Range: 0–86400)
  - `new_key_expires_at`: string (date-time) | null (required) — RFC 3339 datetime string of when the API key should expire after this rotation. Applied when the new secret is activated. If omitted, the API key keeps its current expiry.
  - `expires_at`: string (date-time) | null (required) — RFC 3339 datetime string of when the old secret stops working. `null` until the new secret is activated.
  - `status`: string (required) — Status of this API key rotation.
    - `pending` — Rotation was created and the new secret was issued, but it hasn't been used yet. The current secret still works.
    - `completed` — The new secret was used and is now active. The old secret works until `expires_at`.
    - `canceled` — Rotation was canceled or replaced by a newer rotation before the new secret was used.
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
  - `pagination`: object (required) — Keys used for working with paginated results.
    - `per_page`: integer (required) — Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
    - `next`: string (uri) (required) — URL containing the query parameters of the original request, along with the `after` parameter that marks the starting point of the next page. Always returned, even if `has_more` is `false`.
    - `has_more`: boolean (required) — Whether this response has another page.
    - `estimated_total`: integer — Estimated number of entities for this response.

For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns `100001` to indicate that more than 100,000 entities match. Returns `-1` when counting is skipped or couldn't be calculated.

Use `has_more` and `next` to page through all results rather than relying on `estimated_total` for an exact count.

### Response example

```json
{
  "data": [
    {
      "id": "apkrot_01kjnm4a3w4jqdbtqvb2jwjdf7",
      "api_key_id": "apikey_01jkdpbhazdpn3wpcya45as9tg",
      "new_key": "pdl_live_apikey_01jkdpbhaz****",
      "grace_period_seconds": 3600,
      "new_key_expires_at": "2026-11-02T00:00:00Z",
      "expires_at": "2026-10-02T10:05:00.000Z",
      "status": "completed",
      "created_at": "2026-10-02T09:00:00.000Z",
      "updated_at": "2026-10-02T09:05:00.000Z"
    }
  ],
  "meta": {
    "request_id": "b2b4b6d7-6b7a-4b8e-9b3e-7a4d9f2a5c6e",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/api-keys/apikey_01jkdpbhazdpn3wpcya45as9tg/rotations?after=apkrot_01kjnm4a3w4jqdbtqvb2jwjdf7",
      "has_more": false,
      "estimated_total": 1
    }
  }
}
```