Get a test clock · Ownrecord docs

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`	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`	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`	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: validation_failed, api_version_unsupported, authentication_required, api_key_invalid, scope_required, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

A clock after an advance#

Errors#