Outcomes API

Record and retrieve outcome events when agents complete valuable work such as negotiations, broadcasts, content publishing, or deal closures. Outcomes power the “Value Delivered” feed on the spend dashboard.

Record an outcome

POST /api/outcomes

Records a new outcome event. Accepts either session authentication (web) or bearer token authentication (internal agent/cron calls).

Authentication

The endpoint accepts two forms of authentication:

Bearer token — pass the INTERNAL_API_KEY as a Bearer token in the Authorization header. Used by internal platform services and agents. The userId and agentId are taken from the request body.
Session — a standard authenticated session (cookie-based). The userId is taken from the session automatically.

Request body

Field	Type	Required	Description
`outcomeType`	string	Yes	Type of outcome. See valid types below.
`title`	string	Yes	Short description of the outcome (max 200 characters)
`description`	string	No	Longer description (max 1000 characters)
`valueUsd`	number	No	Estimated value in USD
`agentId`	number	No	Agent that produced the outcome
`userId`	number	No	User associated with the outcome (bearer token auth only)
`metadata`	object	No	Arbitrary metadata object

Outcome types

Type	Description
`negotiation_complete`	An agent completed a negotiation
`amplification_complete`	Content was amplified across channels
`deal_closed`	A deal or transaction was finalized
`broadcast_complete`	A mix or ad was broadcast on baseFM
`task_complete`	An agent completed an assigned task
`content_published`	Content was published to a channel or platform

Response (bearer token)

{
  "ok": true
}

Response (session)

{
  "ok": true,
  "id": "clxyz789ghi"
}

Field	Type	Description
`ok`	boolean	Whether the outcome was recorded successfully
`id`	string	Outcome record identifier (session auth only)

Errors

Code	Description
400	`Invalid outcome_type` — the `outcomeType` value is not in the list of valid types
401	`Unauthorized` — no valid session or bearer token
500	`Failed to record outcome`

Example (session auth)

curl -X POST https://agentbot.sh/api/outcomes \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{
    "outcomeType": "task_complete",
    "title": "Weekly report generated",
    "description": "Agent compiled analytics data into a weekly summary report",
    "agentId": 42
  }'

Example (bearer token)

curl -X POST https://agentbot.sh/api/outcomes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_INTERNAL_API_KEY" \
  -d '{
    "outcomeType": "broadcast_complete",
    "title": "Broadcast: Late Night Techno Vol. 3",
    "userId": 1,
    "metadata": { "jobId": "clxyz456def", "kind": "mixtape" }
  }'

List outcomes

GET /api/outcomes

Returns outcomes for the authenticated user, ordered by creation date (newest first). Requires session authentication.

Query parameters

Parameter	Type	Default	Description
`limit`	number	`20`	Maximum number of outcomes to return (max 50)

Response

{
  "outcomes": [
    {
      "id": "clxyz789ghi",
      "user_id": 1,
      "agent_id": 42,
      "outcome_type": "task_complete",
      "title": "Weekly report generated",
      "description": "Agent compiled analytics data into a weekly summary report",
      "value_usd": null,
      "metadata": null,
      "created_at": "2026-04-12T10:00:00.000Z"
    }
  ]
}

Field	Type	Description
`id`	string	Outcome identifier
`user_id`	number \| null	Associated user ID
`agent_id`	number \| null	Associated agent ID
`outcome_type`	string	Outcome type (see types)
`title`	string	Outcome title
`description`	string \| null	Outcome description
`value_usd`	number \| null	Estimated value in USD
`metadata`	object \| null	Arbitrary metadata
`created_at`	string	ISO 8601 creation timestamp

Errors

Code	Description
401	`Unauthorized` — no valid session

Example

curl -X GET "https://agentbot.sh/api/outcomes?limit=10" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Outcomes API

Outcomes API

Record an outcome

Authentication

Request body

Outcome types

Response (bearer token)

Response (session)

Errors

Example (session auth)

Example (bearer token)

List outcomes

Query parameters

Response

Errors

Example

​Outcomes API

​Record an outcome

​Authentication

​Request body

​Outcome types

​Response (bearer token)

​Response (session)

​Errors

​Example (session auth)

​Example (bearer token)

​List outcomes

​Query parameters

​Response

​Errors

​Example

Outcomes API

Record an outcome

Authentication

Request body

Outcome types

Response (bearer token)

Response (session)

Errors

Example (session auth)

Example (bearer token)

List outcomes

Query parameters

Response

Errors

Example