Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

List test clocks for the active tenant

GET

/v1/test-clocks

const url = 'http://localhost:8080/v1/test-clocks?limit=50&offset=0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:8080/v1/test-clocks?limit=50&offset=0' \
  --header 'Authorization: Bearer <token>'

Test mode only — returns 403 in live mode. Test clocks let operators simulate time-bound billing flows without waiting for wall-clock advances. See ADR / docs for the simulator semantics.

Authorizations

BearerAuth

Parameters

Query Parameters

limit

integer

default: 50 >= 1 <= 100

Rows per page, from 1 to 100. Default 50. Any other value, or one that is not a whole number, is a 422 with param: limit.

offset

integer

Rows to skip, 0 or more. Default 0. A negative value, or one that is not a whole number, is a 422 with param: offset.

Responses

200

Test clocks

application/json

object

data

required

Array<object>

A clock for test mode. Customers and subscriptions attached to it are billed on its time, not the real time.

object

required

string

tenant_id

string

name

required

string

frozen_time

required

The clock’s current time.

string format: date-time

status

required

ready: it can be advanced or deleted. advancing: billing is catching up to the new time. internal_failure: the last advance failed partway; resume it with POST /v1/test-clocks/{id}/retry-advance.

string

Allowed values: ready advancing internal_failure

created_at

required

string format: date-time

updated_at

required

string format: date-time

last_failure_reason

Why the last advance failed. Cleared by the next successful advance.

string

last_advance_summary

What the latest advance did: the time span it covered and how many of each billing step it ran. Absent until the clock is first advanced.

object

advanced_from

required

string format: date-time

advanced_to

required

string format: date-time

invoices_generated

required

integer

trials_activated

required

integer

pauses_resumed

required

integer

thresholds_fired

required

integer

tax_retried

required

integer

charges_retried

required

integer

clawbacks_issued

required

integer

credits_expired

required

integer

dunning_advanced

required

integer

had_errors

required

True when a step failed. The counts then cover only the work done before the failure.

boolean

total

required

How many rows match the request’s filters, on every page, not only this one. The audit log and the customer list’s search and name or email sort say where they stop counting.

integer

Example

{
  "data": [
    {
      "status": "ready"
    }
  ]
}

403

Caller is in live mode

application/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

422

limit or offset is out of range or not a whole number, or the request sends the removed after cursor (param names it)

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}