API Reference

API: Analytics

Flapjack REST API endpoints for usage analytics, cost tracking, and per-model breakdowns.

Query aggregated usage and cost metrics for your organization, with breakdowns by agent, model, and day.

Organization Analytics

GET /api/analytics

Parameter	Type	Default	Description
`period`	`string`	`30d`	Time window: `7d`, `30d`, or `90d`
`agentId`	`uuid`	—	Filter to a single agent

Response:

{
  "period": {
    "start": "2026-04-04T00:00:00Z",
    "end": "2026-05-04T12:00:00Z",
    "days": 30
  },
  "summary": {
    "unique_users": 42,
    "unique_sessions": 150,
    "total_threads": 310,
    "total_turns": 1820,
    "input_tokens": 4500000,
    "output_tokens": 1200000,
    "cache_read_tokens": 800000,
    "cache_write_tokens": 200000,
    "tool_calls": 540,
    "estimated_cost_usd": 85.50,
    "avg_response_time_ms": 2400
  },
  "daily": [
    {
      "day": "2026-04-04",
      "unique_users": 5,
      "total_threads": 12,
      "total_turns": 65,
      "input_tokens": 150000,
      "output_tokens": 40000,
      "estimated_cost_usd": 2.85
    }
  ],
  "by_agent": [
    {
      "agent_id": "agent-uuid",
      "total_turns": 900,
      "estimated_cost_usd": 42.00
    }
  ],
  "by_model": [
    {
      "model": "claude-opus-4-7-20250430",
      "total_turns": 1200,
      "estimated_cost_usd": 60.00
    }
  ],
  "top_tools": [
    { "tool_name": "web_search", "call_count": 210 },
    { "tool_name": "database_query", "call_count": 180 }
  ]
}

curl "https://api.flapjack.dev/api/analytics?period=7d" \
  -H "Authorization: Bearer fj_live_..."

Runner Analytics

GET /api/runners/{runnerId}/analytics

Per-runner execution metrics with cost breakdown by model.

Parameter	Type	Default	Description
`period`	`string`	`30d`	Time window: `7d`, `30d`, or `90d`

Response:

{
  "runner": { "id": "runner-uuid", "name": "Product Discovery" },
  "period": { "days": 30, "since": "2026-04-04T00:00:00Z" },
  "summary": {
    "total_runs": 150,
    "completed": 140,
    "failed": 8,
    "cancelled": 2,
    "pending": 0,
    "success_rate": 93.33,
    "avg_duration_ms": 45000,
    "total_input_tokens": 2000000,
    "total_output_tokens": 500000,
    "total_cost_usd": 35.50,
    "avg_cost_per_run_usd": 0.2536
  },
  "cost_by_model": [
    { "model": "claude-opus-4-7-20250430", "cost_usd": 30.00 },
    { "model": "gpt-5.4-nano", "cost_usd": 5.50 }
  ],
  "daily": [
    {
      "day": "2026-04-04",
      "total_runs": 5,
      "completed": 5,
      "failed": 0,
      "cost_usd": 1.20
    }
  ]
}

curl "https://api.flapjack.dev/api/runners/{runnerId}/analytics?period=7d" \
  -H "Authorization: Bearer fj_live_..."

The cost_by_model array breaks down total cost across all models used during the period. This is sourced from cost_events and includes both main inference and compaction costs.

Cost Tracking

Flapjack tracks costs at two levels:

Source	Table	Scope
Usage events	`usage_events`	Per-turn: tokens, latency, tool calls
Cost events	`cost_events`	Per-operation: provider, model, category

Cost event categories: llm, embedding, web_search, web_research, web_read, web_crawl.

When compaction occurs, the compaction cost is recorded as a separate cost_events row with the compaction model (same model for Anthropic; gpt-5.4-nano for OpenAI), keeping per-model-rate analysis accurate.

Next Steps

API: Runners — runner CRUD and connections
Concepts: Compaction — how compaction costs are tracked
API: Logs — per-trace token and cost details