---
title: "Claim a run - THE spend gate"
method: POST
path: "/api/funko/run/start"
tags: ["funko", "browser-session"]
---

# Claim a run - THE spend gate

`POST /api/funko/run/start`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/funko/run/start`
- Auth: API key in cookie `__session`

Clerk-session only. The one route that can authorize spending: everything paid downstream demands a runId this issued to the caller. By the time it returns the member has ALREADY been charged (`generationsUsed` is incremented before the runId exists), so a crash mid-run costs the member their allowance rather than the card. The claim is atomic single-winner, so two tabs still produce exactly one run. The agent-token path is the MCP tool `ic_funko_generate_start` (scope funko:write), which spends through the same claim, then `ic_funko_generate_step` / `ic_funko_generate_status` drive the run server-side.

## Response `200`

The run id plus the caller's remaining allowance.

- FunkoRunStartResponse
  - `ok` boolean, required
  - `runId` string, required: Pass this to every paid route for the life of the run.
  - `remaining` integer: Allowance left AFTER this run was charged.

## Other responses

- `401`: Not signed in.
- `403`: Quota denied - out of allowance, a run already in flight, or the floor's daily ceiling. `reason` says which.
- `500`: KV failed - the gate fails CLOSED.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)