GovDash
Menu

Agent runs

Start an agent run

Starts a manual run asynchronously and returns the run. Send an Idempotency-Key header to make a retry safe. Credit enforcement returns 402; missing run permission returns 403.

posthttps://api.govdash.us/v1/agents/{id}/runs

Authorization

Authorizationstringheaderrequired

Your API key as a bearer token, for example Bearer gd_live_....

See Authentication for how to create a key.

Path parameters

idstringpathrequired

Headers

idempotency-keystringheader

Makes a retried request safe. Reuse the same key to retry; the original result is returned instead of repeating the action. Keys are kept for 60 minutes. 1 to 255 printable ASCII characters.

govdash-versionenumheaderrequired

The dated API version this request is written against. Responses keep that version's shape after newer versions ship.

One of:2026-11-17

Body

application/json
inputobject
Show child attributes
opportunity_idstring
proposal_idstring
document_idstring
award_idstring

Response

202 · application/json
idstring
objectstring
team_idstring
created_atstring (date-time)

When the run was created.

updated_atstring (date-time)

Latest run start or completion time.

agent_idstring
agent_versioninteger
statusenum

One of:QUEUEDRUNNINGSUCCEEDEDFAILEDACTION_REQUIREDREFUSEDCANCELEDTIMED_OUTSYSTEM_TERMINATED

trigger_typeenum

One of:OUTLOOK_EMAIL_RECEIVEDMANUALMONITORSCHEDULEOPPORTUNITY_CREATEDOPPORTUNITY_STAGE_CHANGEDPROPOSAL_CREATEDDOCUMENT_UPLOADEDOPPORTUNITY_DOCUMENT_UPLOADEDPROPOSAL_SOLICITATION_DOCUMENT_ADDEDCONTRACT_DOCUMENT_UPLOADEDCONTRACT_AWARDED

started_by_user_idstring
run_as_user_idstring
started_atstring (date-time)

When the run started.

completed_atstring (date-time) | null

When the run completed.

inputobject
Show child attributes
opportunity_idstring
proposal_idstring
document_idstring
award_idstring
result_messagestring | null
failure_reasonstring | null
thread_idstring | null
classificationenum

One of:UNCLASSIFIEDCUI

credits_usednumber | null

Errors

Every error returns a stable error.code to branch on and an error.message that says what went wrong, like the examples below. See Errors for how to handle each one.

400bad_request

A path or query parameter is malformed.

Invalid request path parameters: Expected a non-empty string

401unauthorized

The API key is missing, mistyped, revoked, or expired.

The bearer token is missing or invalid.

402quota_exceeded

Your team has used up a quota this request needs, such as agent credits. The message says which.

403forbiddenclassification_out_of_scope

The key's service account doesn't have the permission this needs, or your team's access has ended.

You do not have permission to perform this action.

404not_found

The record doesn't exist, belongs to another team, or is above the key's classification.

The requested resource was not found.

409conflict

A record like this already exists. Use it instead of creating another.

The request conflicts with an existing resource.

413payload_too_large

The request body is over 1 MB.

The request body must not exceed 1 MB.

422validation_failed

The request is well formed, but GovDash won't make this change. The message says why, when it can.

The request failed validation.

429rate_limited

You sent too many requests. Wait the seconds in the retry-after header, then retry.

This access token exceeded its write rate limit.

500internal_error

Something went wrong on GovDash's side, usually a bug. Retry with backoff, and check before retrying a create.

An unexpected error occurred.

503service_unavailable

GovDash is briefly unavailable and didn't run the request. Retry after retry-after.

The service is temporarily unavailable. Try again later.

post/v1/agents/{id}/runs

Start an agent run

Sends a real POST request that changes your team's data.

Path parameters
string, required
Body

Starts with the required fields. The Body section of this page lists every field.

Bearer

Kept in this tab only. Use a key you can revoke.

Request
Response
Send the request to see the response.