Stateful Mocks

Starter, Pro, and Enterprise only.

What are stateful mocks?

A stateful mock is an endpoint that cycles through a sequence of responses instead of always returning the same one. Each time the endpoint is called, it advances to the next step in the sequence.

This lets you simulate real-world workflows where the same endpoint returns different results depending on what has happened before — without writing any server code.

---

When to use them

Workflow	Steps
OAuth authorization	pending → authorized → token expired
Async job	queued → processing → complete
Inventory	in_stock → low_stock → out_of_stock
Pagination	Page 1 → Page 2 → Page 3 → empty
Payment	processing → succeeded

---

Configuring a state sequence

In the dashboard, click the pencil icon next to any endpoint, then open the State Sequence tab.

A state sequence is an ordered list of steps. Each step has:

Field	Required	Description
status_code	Yes	HTTP status code for this step
body	No	JSON or string response body
headers	No	Custom response headers
repeat	No	How many times to return this step before advancing (default: 1)
sticky	No	If true, stay on this step forever instead of advancing

The last step in a sequence is always sticky by default — it repeats forever once reached.

---

Example: async job status

This sequence simulates polling a job status endpoint:

Step 1 — First call returns queued:

{ "status": "queued", "progress": 0 }

Step 2 — Second and third calls return processing (repeat: 2):

{ "status": "processing", "progress": 50 }

Step 3 — All subsequent calls return complete (sticky):

{ "status": "complete", "progress": 100, "result_url": "/results/abc" }

---

Example: OAuth flow

Step 1 — Authorization pending:

Status: 202 Accepted

{ "status": "pending", "message": "Waiting for user authorization" }

Step 2 — Authorized (sticky):

Status: 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

---

Resetting state

State is tracked per endpoint, per namespace. To reset an endpoint back to step 1:

Single endpoint — Click Reset state on the endpoint's config panel in the dashboard.

Entire namespace — Click Reset all state from the workspace overview. This resets every stateful endpoint in the workspace simultaneously.

Via API — Send a POST request (useful in CI teardown):

# Reset single endpoint
curl -X POST https://api.mockra.io/mock-configs/{id}/reset-state \
  -H "Authorization: Bearer {token}"

# Reset entire workspace
curl -X POST https://api.mockra.io/workspaces/{id}/reset-state \
  -H "Authorization: Bearer {token}"

---

Removing stateful behavior

To revert an endpoint to a plain static response, open the State Sequence tab and click Remove state config. The endpoint reverts to returning whatever is set in its static mock config.

---

How state is tracked

State is stored in Cloudflare Durable Objects — one per namespace. Each Durable Object tracks the current step index for every stateful endpoint in that namespace.

This means:

• State is global per namespace — all clients calling the same endpoint share the same state
• State persists until explicitly reset
• State advances immediately after each call — there is no race condition for concurrent requests (the Durable Object serializes access)

If you need per-client state isolation, use ephemeral namespaces — one namespace per test client or test run.

---

State config API

See the API Reference for the full state_configs endpoint documentation.