---
title: "control the server clock for deterministic time-based testing"
method: PUT
path: "/mockserver/clock"
tags: ["control"]
---

# control the server clock for deterministic time-based testing

`PUT /mockserver/clock`

## Request

- Base URL: `http://localhost:1080`
- URL: `http://localhost:1080/mockserver/clock`
- Auth: none declared

Freeze, advance, or reset MockServer's internal clock. The controllable clock affects response template date/time helpers (now_iso_8601, now_epoch, now_rfc_1123, dates.*) and expectation TimeToLive expiry. Event-log timestamps and JWT issuance are not affected.

## Request body

- ClockRequest: clock control request
  - `action` 'freeze' | 'advance' | 'reset', required: freeze: freeze the clock at the given instant (or current time if instant is omitted); advance: advance the frozen clock by durationMillis (freezes first if not already frozen); reset: reset the clock to real wall-clock time
  - `instant` string, date-time: ISO-8601 instant to freeze at (only used with action 'freeze'; omit to freeze at current time)
  - `durationMillis` integer: number of milliseconds to advance the clock by (required when action is 'advance')

## Response `200`

clock action applied successfully

- ClockResponse: clock control response after a freeze, advance, or reset action
  - `status` string: the action that was performed (freeze, advance, or reset)
  - `currentInstant` string, date-time: the current server clock instant after the action
  - `currentEpochMillis` integer: the current server clock time as epoch milliseconds after the action

## Other responses

- `400`: incorrect request format (missing or invalid action, invalid instant, non-positive duration)

---

[API](https://skmtc.dev/mock-server/apis/mockserver-api.md) · [All operations](https://skmtc.dev/mock-server/apis/mockserver-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mock-server/apis/mockserver-api/revisions/9239b693996e?raw)