Run an agent

POST /v1/agents/:id/runs

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

Body field	Type	Notes
message	string	Or messages.
messages	array	{ role, content } objects; first and last from the user.
metadata	object	Optional, ≤ 2 KB, stored on the 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?"}'

Returns 201 with the run. Runs usually take a few seconds; allow up to a few minutes for long tool chains.

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"
}

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