Run agents
In this example you'll create an agent, start a run, read its result, and cancel a run you no longer need. It builds on the Quickstart, so set GOVDASH_API_URL, GOVDASH_API_KEY, and GOVDASH_API_VERSION the same way.
You need:
- A service account whose role has the agent permissions for what you'll do. The API checks the role on every call, so a missing permission returns
403 forbidden. - The id of a team member to run the agent as. The run acts as that member, and the member must meet the same rules as in GovDash.
1. Create an agent
Send POST /v1/agents. name, goal_prompt, visibility, run_as_user_id, and tool_bundles are required.
| Field | What it does |
|---|---|
goal_prompt | The instructions the agent follows on every run. |
visibility | PERSONAL keeps the agent to its owner. TEAM shares it with your team. |
run_as_user_id | The team member the agent acts as. |
tool_bundles | The groups of GovDash tools the agent may use, such as CAPTURE or PROPOSAL. The API reference lists every value. |
triggers | What starts the agent. MANUAL is for runs you start through the API. SCHEDULE runs on a cron schedule and needs cron_expression and timezone. Other types start the agent when something happens in GovDash, such as OPPORTUNITY_CREATED. |
Set RUN_AS_USER_ID to the id of the team member the agent should act as. This example creates an agent you can run manually:
curl "$GOVDASH_API_URL/v1/agents" \
-X POST \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION" \
-H "Content-Type: application/json" \
-d '{
"name": "Pipeline summary",
"goal_prompt": "Summarize our pipeline changes.",
"visibility": "TEAM",
"run_as_user_id": "'"$RUN_AS_USER_ID"'",
"tool_bundles": ["CAPTURE"],
"triggers": [{"type": "MANUAL", "enabled": true}]
}'const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const response = await fetch(`${process.env.GOVDASH_API_URL}/v1/agents`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Pipeline summary",
goal_prompt: "Summarize our pipeline changes.",
visibility: "TEAM",
run_as_user_id: process.env.RUN_AS_USER_ID,
tool_bundles: ["CAPTURE"],
triggers: [{ type: "MANUAL", enabled: true }],
}),
})
if (!response.ok) throw new Error(await response.text())
const agent = await response.json()
console.log(agent.id)import os
import requests
response = requests.post(
os.environ["GOVDASH_API_URL"] + "/v1/agents",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
},
json={
"name": "Pipeline summary",
"goal_prompt": "Summarize our pipeline changes.",
"visibility": "TEAM",
"run_as_user_id": os.environ["RUN_AS_USER_ID"],
"tool_bundles": ["CAPTURE"],
"triggers": [{"type": "MANUAL", "enabled": True}],
},
)
response.raise_for_status()
print(response.json()["id"])A 201 returns the agent, including its id. You can start a run of any agent through the API, whatever its triggers are.
Change an agent with PATCH /v1/agents/{id}. Omitted fields keep their values, with one exception: an update replaces the entire triggers set. Sending {"triggers":[]} removes every trigger and its schedule.
Warning
Deleting an agent with DELETE /v1/agents/{id} cancels its active runs,
deletes its run history, and removes its schedules. You can't undo it. To stop
an agent without losing its history, PATCH it with {"enabled": false}.
2. Start a run
Send POST /v1/agents/{id}/runs with {} to start a manual run. To point the run at a record, pass its id in input: opportunity_id, proposal_id, document_id, or award_id.
Save the agent's id as AGENT_ID. Create an IDEMPOTENCY_KEY once for the run, for example with export IDEMPOTENCY_KEY="$(uuidgen)", and reuse it for any retries.
curl "$GOVDASH_API_URL/v1/agents/$AGENT_ID/runs" \
-X POST \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{}'const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const idempotencyKey = process.env.IDEMPOTENCY_KEY
if (!idempotencyKey) throw new Error("Set IDEMPOTENCY_KEY once per run")
const response = await fetch(
`${process.env.GOVDASH_API_URL}/v1/agents/${process.env.AGENT_ID}/runs`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
"Idempotency-Key": idempotencyKey,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
},
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())import os
import requests
response = requests.post(
f"{os.environ['GOVDASH_API_URL']}/v1/agents/{os.environ['AGENT_ID']}/runs",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
"Idempotency-Key": os.environ["IDEMPOTENCY_KEY"],
},
json={},
)
response.raise_for_status()
print(response.json())The response is 202 Accepted with an agent_run object. The run hasn't finished yet. Its status is QUEUED or RUNNING, and its id identifies the run.
Two refusals are specific to starting a run:
402 quota_exceededmeans the team is out of agent credits. Retrying won't help until credits are added.403 forbiddenmeans the service account's role can't run agents.
Warning
Starting a run consumes credits. Send an Idempotency-Key header with a
unique value, and reuse it if the request times out. A retry with the same key
returns the original run once its creation has completed. An unresolved
attempt can return 409; check recent runs before trying a new key. See
Retry safely.
3. Read the run
Send GET /v1/agent-runs/{id} to read a run's status and result.
curl "$GOVDASH_API_URL/v1/agent-runs/$RUN_ID" \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION"const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const response = await fetch(
`${process.env.GOVDASH_API_URL}/v1/agent-runs/${process.env.RUN_ID}`,
{
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
},
},
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())import os
import requests
response = requests.get(
f"{os.environ['GOVDASH_API_URL']}/v1/agent-runs/{os.environ['RUN_ID']}",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
},
)
response.raise_for_status()
print(response.json())Runs can take minutes. Poll periodically until the run reaches a terminal status; avoid polling continuously. We are rebuilding webhooks and hope to publish the updated API by the end of 2026.
| Status | Meaning |
|---|---|
QUEUED | Accepted and waiting to start. |
RUNNING | In progress. |
SUCCEEDED | Finished. The answer is in result_message. |
FAILED | Stopped with an error. The reason is in failure_reason. |
ACTION_REQUIRED | Stopped because it needs a person to act in GovDash. failure_reason says what. |
REFUSED | GovDash declined to run it. |
CANCELED | Stopped by a cancel request. |
TIMED_OUT | Ran past its time limit. |
SYSTEM_TERMINATED | Stopped by GovDash rather than by a cancel request. |
A run in ACTION_REQUIRED can still become SUCCEEDED once someone resolves it in GovDash.
If a run's thread is classified above what your key can read, the response keeps the run's metadata and classification but leaves out result_message, failure_reason, and input. See Classification.
Add expand[]=credits to include credits_used. It's null until a finished run has ledger entries.
4. Cancel a run
Send POST /v1/agent-runs/{id}/cancel to stop a run you no longer need. The response is the run, with its latest status.
curl "$GOVDASH_API_URL/v1/agent-runs/$RUN_ID/cancel" \
-X POST \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION"const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const response = await fetch(
`${process.env.GOVDASH_API_URL}/v1/agent-runs/${process.env.RUN_ID}/cancel`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
},
},
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())import os
import requests
response = requests.post(
f"{os.environ['GOVDASH_API_URL']}/v1/agent-runs/{os.environ['RUN_ID']}/cancel",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
},
)
response.raise_for_status()
print(response.json())List runs
GET /v1/agent-runs lists your team's runs, most recently started first. It pages like the other list endpoints. See Pagination.