API Reference

Reports

The Reports API returns aggregated usage and cost data. Reports are computed on-demand from the underlying event store. For large date ranges, add async=true to get a job ID you can poll.

Usage report

GET /api/v1/reports/usage

Parameter	Type	Required	Description
`from`	ISO 8601	Yes	Start of reporting window
`to`	ISO 8601	Yes	End of reporting window
`group_by`	string	No	`day` \| `week` \| `month` \| `user` \| `project` \| `model`
`user_id`	string	No	Filter by user
`project_id`	string	No	Filter by project
`team_id`	string	No	Filter by team

curl "https://forg.pro/api/v1/reports/usage?from=2025-05-01&to=2025-05-31&group_by=day" \
  -H "Authorization: Bearer forg_live_..."

{
  "period": { "from": "2025-05-01", "to": "2025-05-31" },
  "totals": {
    "tokens_in":   4820000,
    "tokens_out":  1240000,
    "sessions":    847,
    "events":      12483
  },
  "data": [
    { "date": "2025-05-01", "tokens_in": 184230, "tokens_out": 48120, "sessions": 28, "events": 412 },
    { "date": "2025-05-02", "tokens_in": 192840, "tokens_out": 51300, "sessions": 31, "events": 438 },
    ...
  ]
}

Cost report

GET /api/v1/reports/cost

Same parameters as the usage report. Returns cost breakdowns:

{
  "period": { "from": "2025-05-01", "to": "2025-05-31" },
  "totals": {
    "cost_usd": 1284.72,
    "sessions": 847
  },
  "data": [
    {
      "date":     "2025-05-01",
      "cost_usd": 41.23,
      "breakdown": {
        "claude-opus-4-5": 31.10,
        "claude-sonnet-4": 7.82,
        "gpt-4o":          2.31
      }
    },
    ...
  ]
}

Model breakdown report

GET /api/v1/reports/models

{
  "period": { "from": "2025-05-01", "to": "2025-05-31" },
  "data": [
    {
      "model":       "claude-opus-4-5",
      "tokens_in":   3120000,
      "tokens_out":  820000,
      "cost_usd":    984.24,
      "share_pct":   76.6,
      "events":      9840
    },
    {
      "model":       "claude-sonnet-4",
      "tokens_in":   1400000,
      "tokens_out":  380000,
      "cost_usd":    240.16,
      "share_pct":   18.7,
      "events":      2284
    }
  ]
}

Async reports

For date ranges over 90 days, add async=true to any report endpoint. The response returns a job ID:

POST /api/v1/reports/usage?async=true
{ "from": "2024-01-01", "to": "2025-01-01", "group_by": "month" }

// Response:
{ "job_id": "job_8f3e1b2c", "status": "queued", "eta_seconds": 12 }

// Poll:
GET /api/v1/reports/jobs/job_8f3e1b2c
{ "job_id": "job_8f3e1b2c", "status": "complete", "result_url": "https://..." }