List agent runs
List this company's agent runs, past and in progress, with their status and which definition they came from. Use it to find a run id, or to check whether an agent is already working before starting another one.
Authentication
sf_… API key in the bearerAuth field below.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
1 <= lengthResponse Body
application/json
curl -X GET "https://example.com/companies/string/agent_runs"[ { "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" }]List agent definitions
List the agents that can be run for this company, each with a title and a description of what it does. The `id` here is the `definitionId` you pass when starting a run. Read this first rather than hard-coding an id, since the catalogue changes as agents are added.
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`).