Skip to content
GasketDocs

Runs

One call to an agent, from message to reply.

A run sends your messages to the model with the agent's instructions and tools. When the model calls a tool, Gasket decides it with the policy, calls your endpoint if allowed, and gives the model the result. This repeats until the model replies or the agent's max steps are reached.

POST/v1/agents/:id/runsscope agents:run

curl https://usegasket.xyz/api/v1/agents/agt_.../runs \
  -H "Authorization: Bearer $GASKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Where is my order 4821?"}'

Input

  • message: a string, or
  • messages: an array of { role: "user" | "assistant", content: string }, first and last from the user, up to 100 messages and 64,000 characters.
  • metadata (optional): a small object stored on the run.

Runs are stateless: send the conversation you want the agent to see. Gasket does not keep memory between runs.

Statuses

statusMeaning
completedThe agent replied. output.text has the reply.
requires_approvalA tool call needs a person. pending_action_id says which. Continue the run after it's decided.
failedThe run stopped. error.code says why: model_error, model_rate_limited, insufficient_credit, spend_limit_reached, max_steps_reached, model_refused.

Response

json
{
  "id": "run_...",
  "object": "run",
  "agent_id": "agt_...",
  "environment": "test",
  "status": "completed",
  "model": "claude-haiku-5-5",
  "output": { "text": "Order 4821 is out for delivery and should arrive by 6pm." },
  "pending_action_id": null,
  "steps": [
    { "type": "model", "input_tokens": 912, "output_tokens": 64, "cost_micros": 124, "stop_reason": "tool_use" },
    { "type": "tool", "tool": "lookup_order", "action_id": "act_...", "decision": "authorized", "status": "succeeded", "http_status": 200 },
    { "type": "model", "input_tokens": 1104, "output_tokens": 41, "cost_micros": 131, "stop_reason": "end_turn" }
  ],
  "usage": { "input_tokens": 2016, "output_tokens": 105, "cost_micros": 20255 },
  "error": null,
  "request_id": "req_...",
  "created_at": "2026-10-15T12:41:08.000Z",
  "completed_at": "2026-10-15T12:41:11.000Z"
}

Usage

usage.cost_micros is the run's total: model tokens at Claude Haiku 5.5's price plus one action charge per tool call. 1,000,000 micros = $1.

Something wrong or missing? Tell us · Stuck? Help center