Track API
Real-time usage tracking for CLI and integrations. This is the control-plane meter, not a general product analytics bus.
Truth note (bs-8328): Request bodies use
type+ optionalcount/metadata. Older docs that showed free-formevent/propertiesobjects were wrong and have been removed. Batched telemetry usesPOST /api/v1/events/batch.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/track | Record a usage event immediately |
POST | /api/v1/events/batch | Batch telemetry events (CLI) |
There is no GET /v1/track/events list route on the public control plane.
Track usage event
Loading code block...
Headers
| Header | Required | Description |
|---|---|---|
Authorization: Bearer bs_… or X-API-Key | Yes | API key with write scope |
X-Project-Id | Recommended | Project context for attribution |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | One of the usage types below |
count | number | No | Defaults to 1, clamped to 1–100 |
metadata | object | No | Free-form metadata (not stored as product analytics) |
Valid type values
| Type | Meaning |
|---|---|
api_calls | Generic API usage |
agents_invoked | Agent invocation |
skills_accessed | Skill/pattern access |
workflows_started | Workflow start |
mcp_calls | MCP tool call |
Example
Loading code block...
Response
Loading code block...
Batch telemetry
Loading code block...
Used by the CLI to ship buffered telemetry. Events map into the same usage types:
| Event name | Maps to usage type |
|---|---|
agent.invoked / agent.invoke | agents_invoked |
skill.accessed / skill.search / skill.view | skills_accessed |
workflow.started / workflow.start | workflows_started |
mcp.tool.call / mcp.call | mcp_calls |
api.call | api_calls |
Example shape
Loading code block...
Integration notes
- Prefer the CLI/MCP for agent work; they already emit usage telemetry.
- Typed SDKs (
@bootspring/sdk, Python, Go) are roadmap-only — use curl,fetch, CLI, or MCP. - Do not invent client wrappers that are not published on npm.