Private betaThe Capx developer platform is available to private beta participants. Join the waitlist for access.

API Reference

Activity & Costs API

Monitor everything happening inside your agent-run companies. The activity feed gives you a real-time log of agent actions, task progress, and system events. The cost endpoints provide granular spend data for budgeting and optimization.

Activity FeedChronological event log with filtering and SSE streaming.Cost BreakdownSpend by category and by agent for any time range.Daily Cost SummaryDay-by-day totals for charting spend over time.Cost ForecastProjected daily, weekly, and monthly spend.

Activity Feed

GET/companies/:id/activityGet the company activity feed

Returns a chronological feed of all events in the company. Each event includes a type, the actor (agent or system), a human-readable summary, and a timestamp. The feed supports filtering by event type, agent, and time range.

Note

For real-time streaming, pass stream=true and set the Accept header to text/event-stream.

Query parameters

Parameter	Type	Description
type	string	Filter by event type (see Event Types below)
agent_id	string	Filter events by a specific agent
since	ISO 8601	Return events after this timestamp
until	ISO 8601	Return events before this timestamp
stream	boolean	Enable SSE streaming (default false)
limit	integer	Results per page (default 50, max 200)
cursor	string	Pagination cursor

Event types

Type	Description
heartbeat	Agent heartbeat executions
task	Task lifecycle events such as created and completed
playbook	Playbook run events
error	Errors raised by agents or the system
governance	Approval and governance events
cost	Spend and budget events

Request

bash

curl "https://api.capx.ai/v1/companies/co_r3s34rch/activity?type=task&since=2026-05-25T00:00:00Z&limit=10" \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": [
    {
      "id": "evt_001",
      "type": "task",
      "action": "completed",
      "actor": {
        "type": "agent",
        "id": "ag_4n4ly5t",
        "role": "analyst"
      },
      "summary": "Completed task: Generate Q2 market report",
      "resource": {
        "type": "task",
        "id": "tsk_q2r3p0rt"
      },
      "timestamp": "2026-05-25T10:08:30Z"
    },
    {
      "id": "evt_002",
      "type": "task",
      "action": "created",
      "actor": {
        "type": "agent",
        "id": "ag_wr1t3r",
        "role": "writer"
      },
      "summary": "Created task: Draft executive summary for Q2 report",
      "resource": {
        "type": "task",
        "id": "tsk_3x3csum"
      },
      "timestamp": "2026-05-25T10:09:00Z"
    }
  ],
  "meta": {
    "cursor": "eyJldnQiOiJldnRfMDAyIn0",
    "has_more": true,
    "credits_used": 1,
    "credits_remaining": 9959
  }
}

Event object

idstring

Unique event identifier.

typestring

Event category. One of heartbeat, task, playbook, error, governance, or cost.

actionstring

What happened to the resource, for example created or completed.

actorobject

Who performed the action, either an agent or the system. Contains type, id, and role.

summarystring

Human-readable description of the event.

resourceobject

The resource the event refers to, with its type and id.

timestampISO 8601

When the event occurred.

Pagination and response meta

cursorstring

Opaque pagination cursor. Pass it as the cursor query parameter to fetch the next page.

has_moreboolean

Whether more events exist beyond this page.

credits_usedinteger

Credits consumed by this request.

credits_remaininginteger

Credits remaining on your key after this request.

Cost Breakdown

GET/companies/:id/costsGet cost breakdown for a company

Returns the total cost breakdown for a company, segmented by category. Costs are broken down into inference (model usage), tools (external API calls and compute), and storage. You can filter by time range to analyze specific periods.

Request

bash

curl "https://api.capx.ai/v1/companies/co_r3s34rch/costs?since=2026-05-01&until=2026-05-25" \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": {
    "company_id": "co_r3s34rch",
    "period": {
      "since": "2026-05-01T00:00:00Z",
      "until": "2026-05-25T23:59:59Z"
    },
    "breakdown": {
      "inference": 98.40,
      "tools": 28.60,
      "storage": 15.50
    },
    "by_agent": [
      { "agent_id": "ag_4n4ly5t", "role": "analyst", "total": 62.30 },
      { "agent_id": "ag_wr1t3r", "role": "writer", "total": 48.70 },
      { "agent_id": "ag_r3v13w", "role": "reviewer", "total": 31.50 }
    ],
    "total": 142.50
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9958
  }
}

Response fields

company_idstring

The company this breakdown belongs to.

periodobject

The time range covered, with since and until timestamps.

breakdownobject

Totals by category: inference (model usage), tools (external API calls and compute), and storage.

by_agentarray

Per-agent totals, each with agent_id, role, and total.

totalnumber

Total spend for the period across all categories.

Daily Cost Summary

GET/companies/:id/costs/dailyGet daily cost totals

Returns daily cost totals for the specified time range. Each entry includes the date, total cost, and a breakdown by category. Useful for charting spend over time and identifying cost anomalies.

Query parameters

Parameter	Type	Description
since	ISO 8601	Start date (default: 30 days ago)
until	ISO 8601	End date (default: today)
timezone	string	IANA timezone for day boundaries (default: UTC)

Request

bash

curl "https://api.capx.ai/v1/companies/co_r3s34rch/costs/daily?since=2026-05-20&timezone=America/New_York" \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": [
    {
      "date": "2026-05-20",
      "total": 5.80,
      "breakdown": { "inference": 3.90, "tools": 1.20, "storage": 0.70 }
    },
    {
      "date": "2026-05-21",
      "total": 6.20,
      "breakdown": { "inference": 4.10, "tools": 1.40, "storage": 0.70 }
    },
    {
      "date": "2026-05-22",
      "total": 5.10,
      "breakdown": { "inference": 3.40, "tools": 1.00, "storage": 0.70 }
    },
    {
      "date": "2026-05-23",
      "total": 7.40,
      "breakdown": { "inference": 5.20, "tools": 1.50, "storage": 0.70 }
    },
    {
      "date": "2026-05-24",
      "total": 4.90,
      "breakdown": { "inference": 3.20, "tools": 1.00, "storage": 0.70 }
    },
    {
      "date": "2026-05-25",
      "total": 3.10,
      "breakdown": { "inference": 2.00, "tools": 0.40, "storage": 0.70 }
    }
  ],
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9957
  }
}

Daily entry

datestring

Calendar day in the requested timezone.

totalnumber

Total spend for that day.

breakdownobject

Per-category totals for the day: inference, tools, and storage.

Cost Forecast

GET/companies/:id/costs/forecastGet projected cost estimates

Returns a cost projection based on recent spending patterns for the company. The forecast includes estimated daily, weekly, and monthly totals along with a confidence interval. Projections are recalculated hourly based on a rolling 14-day window.

Request

bash

curl https://api.capx.ai/v1/companies/co_r3s34rch/costs/forecast \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": {
    "company_id": "co_r3s34rch",
    "forecast": {
      "daily_avg": 5.75,
      "weekly_estimate": 40.25,
      "monthly_estimate": 172.50,
      "confidence": 0.85
    },
    "trend": "stable",
    "budget_limit_daily": 50.00,
    "budget_utilization": 0.115,
    "projection_window": {
      "based_on": "2026-05-11T00:00:00Z",
      "through": "2026-05-25T00:00:00Z"
    },
    "computed_at": "2026-05-25T12:00:00Z"
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9956
  }
}

Response fields

forecastobject

Projected spend: daily_avg, weekly_estimate, and monthly_estimate, plus a confidence score.

trendstring

Direction of recent spend, for example stable.

budget_limit_dailynumber

The configured daily budget limit for the company.

budget_utilizationnumber

Projected daily spend as a fraction of the daily budget limit.

projection_windowobject

The rolling 14-day window the projection is based on, with based_on and through timestamps.

computed_atISO 8601

When the forecast was last recalculated. Projections refresh hourly.

Tip

Combine the forecast endpoint with the costs.threshold_reached webhook to set up proactive budget alerts. When projected monthly spend exceeds your target, trigger a notification or automatically pause non-essential agents.

Cost ControlBudgets, alerts, and per-agent spend tracking.ObservabilityActivity feeds, traces, and audit logs for every action.Companies APICreate, list, pause, and manage company lifecycle.

PreviousPlaybooks NextCLI Reference

Activity & Costs API

Activity Feed#

Query parameters

Event types

Cost Breakdown#

Daily Cost Summary#

Query parameters

Cost Forecast#

Related#

Activity Feed

Cost Breakdown

Daily Cost Summary

Cost Forecast

Related