# Get a test clock

> The test_clocks.get operation: GET /api/v1/test_clocks/{id} in the REST API and the test_clocks_get tool in the MCP server.

Returns a test clock: its time (`frozenTime`), its `status` and its latest advance. After
`test_clocks.advance`, read it until `status` is `ready` (or `internal_failure`, with `advance.error`).

## At a glance

- **REST:** `GET /api/v1/test_clocks/{id}`
- **MCP tool:** `test_clocks_get`
- **Operation ID:** `test_clocks.get`
- **Scope:** Brand
- **Permission:** `subscriptions:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test mode only
- **Authentication:** API key with the `subscriptions:read` scope
- **Since:** M5

## Request

### Path parameters

| Field | Type       | Description |
| ----- | ---------- | ----------- |
| `id`  | `clk_…` ID |             |

### Query parameters

This operation takes no query parameters.

## Response

`200 OK` with a JSON object:

| Field        | Type                                            | Description                                                                                                                                                |
| ------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | `clk_…` ID                                      |                                                                                                                                                            |
| `object`     | `"test_clock"`                                  |                                                                                                                                                            |
| `livemode`   | `false`                                         |                                                                                                                                                            |
| `brandId`    | `brd_…` ID                                      |                                                                                                                                                            |
| `name`       | string                                          |                                                                                                                                                            |
| `frozenTime` | date-time                                       | The clock's time: its customers' subscriptions bill as if it were now.                                                                                     |
| `status`     | one of `ready`, `advancing`, `internal_failure` | `ready`, `advancing` (an advance runs: wait for `ready`) or `internal_failure` (the last advance stopped on an error, see `advance.error`; advance again). |
| `advance`    | object or null                                  | The latest advance.                                                                                                                                        |
| `version`    | integer                                         |                                                                                                                                                            |
| `createdAt`  | date-time                                       |                                                                                                                                                            |
| `updatedAt`  | date-time                                       |                                                                                                                                                            |

## Examples

### A clock after an advance

```http
GET /api/v1/test_clocks/clk_01jacq4m3xf0v8w9zq2y7k5n6h
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "id": "clk_01jacq4m3xf0v8w9zq2y7k5n6h",
  "object": "test_clock",
  "livemode": false,
  "brandId": "brd_01jacq4m3xf0v8w9zq2y7k5n6b",
  "name": "Monthly renewal",
  "frozenTime": "2026-11-21T09:00:00.000Z",
  "status": "ready",
  "advance": {
    "from": "2026-10-20T09:00:00.000Z",
    "to": "2026-11-21T09:00:00.000Z",
    "requestedAt": "2026-10-20T09:00:00.000Z",
    "completedAt": "2026-10-20T09:00:04.000Z",
    "steps": 3,
    "error": null
  },
  "version": 3,
  "createdAt": "2026-10-20T09:00:00.000Z",
  "updatedAt": "2026-10-20T09:00:04.000Z"
}
```

## Errors

| Code                                                                                     | HTTP status | When                                                              | What to do                                                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | No test clock with this ID exists for the brand in test mode.     | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                 |
| [`mode_not_supported`](https://ownrecord.io/docs/reference/errors.md#mode_not_supported) | 400         | The request is in live mode: test clocks exist in test mode only. | Use the mode the operation supports (`details.supported_mode`): test-only operations such as test clocks need test-mode credentials. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)   | 403         | The credentials can't read this brand's subscriptions.            | Ask an organization owner or admin for a role or scope that allows this action.                                                      |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).