SaaSFlow
DevelopersAPIReferenceagent_runs

Retrieve agent run

Retrieve one agent run: its status, the input it was started with, and its result once finished. Poll this after starting a run. Returns 404 if the run does not exist or belongs to another company.

Authentication

You're not signed in. Either sign in at app.saasflow.com and reload (then pick sessionCookie), or paste a SaaSFlow sf_… API key in the bearerAuth field below.
GET
/companies/{companyId}/agent_runs/{id}

Authorization

Authorization<token>

A SaaSFlow API key (format sf_…) or an OAuth bearer token. Paste only the key — the proxy adds the Bearer prefix. Create an API key in Settings → Company settings → API keys — see API keys.

In: header

Path Parameters

companyId*string
Length1 <= length
id*string
Length1 <= length

Response Body

application/json

application/json

curl -X GET "https://example.com/companies/string/agent_runs/string"
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",  "definitionId": "string",  "status": "open",  "triggeredByUserId": "d1704798-c073-4631-a9e3-ed8329695e39",  "suppressNotification": true,  "createdTime": "2019-08-24T14:15:22Z",  "finishedTime": "2019-08-24T14:15:22Z",  "error": "string",  "errorDetails": "string",  "sessionId": "string",  "resumedFromRunId": "666b0c5a-138f-4104-834e-8a1ebe30fa3b",  "cloudRunExecutionId": "string",  "lastHeartbeatTime": "2019-08-24T14:15:22Z",  "costUsd": "string",  "data": "string"}

Create agent run

Start an agent run. `definitionId` comes from the agent-definitions endpoint and `input` carries that agent's parameters. Returns a `runId` immediately; the agent works in the background, so poll the run or its messages. To continue a finished session rather than start fresh, pass `resumeFromRunId` and put the follow-up instruction in `input.prompt`; the earlier transcript is restored. Because agents send company data to an AI provider, a company that has not consented gets 403 with `code: "aiConsentRequired"` and the `providerKey` to request. The caller also needs every permission the agent uses, not just `transactions:read`. One run at a time per company (409), with a per-company rate limit (429, carrying `retryAt`).

List messages

Read the conversation of an agent run, oldest first. Poll with `afterId` set to the last id you saw to stream new messages without refetching the thread. Reading a run requires the permissions the agent itself used, so a caller with narrower access than the person who started it gets 403 rather than a filtered view.