Agent API

Runs

Look up past calls and async runs made with your account, and stop async runs that are still going.

Two kinds of runs share these endpoints:

Calls: every call made with your keys through /gw, /cap, /ai/v1 or a synchronous /v1/run. The run id is the call's X-Pikeway-Call-Id.
Async runs: started with /v1/run and "async": true. Ids start with run_; kept for 7 days with their output.

Authentication

All three endpoints require Authorization: Bearer pk-… and only return runs of the key's account (any key of the account works).

List runs

GET/v1/runs

Query

limitinteger

Page size. Default 20, max 100.

cursorstring

cursor from the previous page.

providerstring

Only calls to this API slug (calls list only).

async1 | true

List async runs instead of calls, including queued and running ones.

statusstring

With async=1: only this status, e.g. RUNNING.

bash

curl "https://gw.pikeway.ai/v1/runs?limit=20" -H "Authorization: Bearer $PIKEWAY_API_KEY"
curl "https://gw.pikeway.ai/v1/runs?async=1&status=RUNNING" -H "Authorization: Bearer $PIKEWAY_API_KEY"

200 OK · calls

{
  "items": [
    {
      "runId": "0192f6b0-5e2a-7d40-b1c3-8f9e2a4d6c11",
      "provider": "birdeye",
      "method": "GET",
      "path": "/defi/price",
      "status": "COMPLETED",
      "providerResponse": { "httpStatus": 200 },
      "cost": { "value": 0.001, "currency": "USD" },
      "durationMs": 214,
      "createdAt": "2026-10-24T09:12:03Z"
    },
    {
      "runId": "0192f6af-11c4-7a0e-9b52-3d7e8f1a2c64",
      "provider": "coingecko",
      "method": "GET",
      "path": "/simple/price",
      "status": "FAILED",
      "providerResponse": { "httpStatus": 502 },
      "cost": { "value": 0, "currency": "USD" },
      "durationMs": 10012,
      "createdAt": "2026-10-24T09:10:47Z",
      "errorOrigin": "UPSTREAM"
    }
  ],
  "cursor": "MjAyNi0xMC0yNFQwOToxMDo0Ny4…"
}

Call fields

statusCOMPLETED | FAILED

FAILED when the logged HTTP status is 400 or above.

pathstring

The path that was called (concrete, not the template).

errorOriginUPSTREAM | USER | GATEWAY

For failed calls: who caused the failure.

With async=1, items have runId, async: true, provider, method, endpoint (the template), status, cost, createdAt and, once done, finishedAt.

Get a run

GET/v1/runs/{runId}

Path

runIdstringrequired

A call id (from X-Pikeway-Call-Id or a sync run) or an async run id (run_…).

bash

curl https://gw.pikeway.ai/v1/runs/run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87 \
  -H "Authorization: Bearer $PIKEWAY_API_KEY"

Async run

200 OK

{
  "runId": "run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87",
  "async": true,
  "provider": "birdeye",
  "method": "GET",
  "endpoint": "/defi/price",
  "status": "COMPLETED",
  "input": { "address": "So11111111111111111111111111111111111111112" },
  "providerResponse": { "httpStatus": 200 },
  "output": { "success": true, "data": { "value": 172.41 } },
  "callId": "0192f6b3-7a10-7e22-a4c5-1b2d3e4f5a6b",
  "cost": { "value": 0.001, "currency": "USD" },
  "timeoutSeconds": 120,
  "createdAt": "2026-10-24T09:20:00Z",
  "startedAt": "2026-10-24T09:20:00Z",
  "finishedAt": "2026-10-24T09:20:01Z",
  "durationMs": 640,
  "pollUrl": "https://gw.pikeway.ai/v1/runs/run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87"
}

statusstring

QUEUED → RUNNING → COMPLETED | FAILED | STOPPED | TIMED_OUT.

outputany

Provider body: JSON, or a string when not JSON. Truncated at 2 MB (error then says so).

errorstring

Why it didn't complete, e.g. stopped by user, run exceeded its timeout, or the gateway's rejection message such as insufficient balance.

callIdstring

The underlying call id, once the call was made.

Call

For a call id you get the same fields as in the list. Response bodies are only kept when the provider enabled detailed logs; then output holds the first 4 KB, otherwise outputRetained is false. Save the output when you make the call if you need it later.

200 OK

{
  "runId": "0192f6b0-5e2a-7d40-b1c3-8f9e2a4d6c11",
  "provider": "birdeye",
  "method": "GET",
  "path": "/defi/price",
  "status": "COMPLETED",
  "providerResponse": { "httpStatus": 200 },
  "cost": { "value": 0.001, "currency": "USD" },
  "durationMs": 214,
  "createdAt": "2026-10-24T09:12:03Z",
  "outputRetained": false
}

Stop a run

POST/v1/runs/{runId}/stop

Stops a queued or running async run. The upstream request is cancelled and nothing is charged. Returns 202 with the run's resulting status (normally STOPPED).

bash

curl -X POST https://gw.pikeway.ai/v1/runs/run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87/stop \
  -H "Authorization: Bearer $PIKEWAY_API_KEY"

202 Accepted

{ "runId": "run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87", "status": "STOPPED" }

Errors

401 missing API key (Authorization: Bearer pk-...) · invalid or revoked API key · 403 key restrictions
404 run not found · run not found (only async runs can be stopped)
405 use GET (or POST /v1/runs/<id>/stop)
409 {"code": 409, "message": "run already finished", "status": "COMPLETED"} when stopping a finished run

Pagination works the same as /v1/wallet/activities: follow cursor until it is null.