Developer documentation API v1
Monitoring and event recovery
Persist bounded tasks and recover events without losing financial state.
Create a monitor
POST /v1/monitors pins an agent revision, research tool and validated input, cadence, overlap rule, maximum service spend per run and optional conditions. Tools with financial_action or mutation effects are not admitted as monitor tools. Monitor runs produce research artifacts and events; separate action workflows retain financial authority.
A monitor has enabled or paused status and a monotonically increasing revision. Updating it requires expected_revision; a stale update returns 409 REVISION_CONFLICT. Pausing prevents new scheduled admissions. A run already admitted remains visible and can be cancelled separately.
Monitor example
Example cadence, spend and freshness threshold. Conditions refer to the documented run-summary fields, not arbitrary executable expressions.
{
"agent_revision_id": "agr_example_3",
"tool": "social.search",
"input": {
"query": "$AAPL lang:en -filter:retweets",
"type": "Latest",
"count": 20
},
"cadence_seconds": 3600,
"overlap_policy": "skip",
"max_service_spend": {
"asset": "SCC",
"atoms": "100",
"scale": 2
},
"conditions": [
{
"field": "source_age_seconds",
"operator": "gt",
"threshold": 7200,
"action": "alert"
}
]
}Conditions and outcomes
| Signal | Interpretation | Permitted response |
|---|---|---|
| source_age_seconds | Maximum age across the latest eligible observation of every required source; null if any required source is absent. | Alert or pause future admissions. |
| coverage_fraction | Available required observations divided by expected observations; null without an expected population. | Alert or pause. |
| consecutive_failures | Consecutive admitted runs ending in failure. | Alert or pause. |
| baseline_loss_delta | Model loss minus baseline loss on matched matured outcomes; null until minimum sample is reached. | Alert or pause. |
Drift is a diagnostic, not a trading rule
A distribution-shift diagnostic compares a fixed reference window with a later window using compatible source coverage and feature definitions. Delayed outcomes are scored only after maturation. Model, data and execution degradation are separate causes; repeated thresholds across many features can generate false alarms. The monitor stores window sizes, minimum sample, threshold and method revision. A trigger does not automatically retrain a model, increase risk or unwind a position.
Read and checkpoint events
GET /v1/events starts with start=earliest or start=latest. The first returns retained history; the second returns an empty batch and a checkpoint at the current watermark. Each batch contains items, next_cursor, resume_cursor and schema_version. Follow next_cursor to drain that bounded batch. Only when next_cursor is null, commit resume_cursor and use after=resume_cursor to poll new events. An empty poll still returns a resumable checkpoint.
Persist checkpoints after applying events durably. Deduplicate by event_id. A missing or stale aggregate revision is resolved from the authoritative resource. data_ref is an authenticated relative API path: job events resolve to /v1/jobs/{id}, action events to /v1/actions/{id}, settlement events to /v1/settlements/{id}, and monitor events to /v1/monitor-runs/{id}.
After 410 EVENT_CURSOR_EXPIRED, first obtain a new start=latest checkpoint, then reconcile the accessible jobs, actions, settlements and monitors from their current resources, and finally consume events after that checkpoint. Revision checks make overlap harmless. Capturing the checkpoint before the resource sweep prevents a gap during recovery. Replay retention follows /v1/connection. The API uses authenticated pull retrieval; no inbound webhook is required.
A disconnected client does not stop work
Scheduled admission, job execution and event publication persist independently of an open browser or MCP session. Reconnecting resumes from resource IDs and checkpoints. Cancellation, pausing a monitor and revoking a financial mandate have distinct effects. An order with an unknown venue outcome stays reserved and reconciles through the execution service.
Nulls, minimum samples and run summaries
GET /v1/monitors/{monitor_id}/runs lists run_id and job_id, timestamps, summary values, missing required sources and matched conditions. GET /v1/monitor-runs/{run_id} retrieves one run. The matched condition records the measured value, threshold and alert/pause response so a client can explain the event.
source_age_seconds is the maximum of the ages of each required source’s latest eligible observation at observed_at. If any required source is absent, the aggregate is null and missing_required_sources identifies the gap. A fresh feed therefore cannot mask a stale dependency.
Numeric conditions evaluate only available finite values. baseline_loss_delta is populated only by evaluation runs with matched matured outcomes and the minimum sample pinned by the evaluation revision; otherwise it is null. Missing data produces a separate event. It is never substituted with zero or an implicit successful condition.