API Reference: Reporting Endpoints

These endpoints read your tracked data — they are what the DevClocked MCP server calls under the hood. All authenticate with the x-devclocked-key header. Unless stated otherwise they are POST with a JSON body, and an empty body applies the documented defaults. Base URL: https://api.devclocked.com/functions/v1.

A shared convention: wherever a project parameter appears, it accepts a project id, display name, canonical repository name, or a saved alias. An unknown name returns 404; a name matching several projects returns 400 with a candidates array so you can retry with an id. Date parameters are YYYY-MM-DD, interpreted in tz (an IANA zone; defaults to your profile timezone, then UTC).

GET /get-today-activity

The day's sessions with their work blocks, minutes, token usage, and cost. Query parameters: date (YYYY-MM-DD, default today) and tz (IANA zone, default profile timezone).

Response 200 (abridged):

{
  "tracked_minutes_today": 292.5,
  "leverage_ratio": 2.4,
  "total_cost_usd": 6.113402,
  "has_unpriced_usage": false,
  "sessions": [
    {
      "id": "0b6f6c3e-9a71-4a86-b9ed-2f4c11f0a915",
      "started_at": "2026-08-09T09:14:02.318Z",
      "ended_at": null,
      "is_active": true,
      "source": "vscode",
      "auto_minutes": 148.32,
      "tracked_in_window": 176.9,
      "tick_count": 184,
      "leverage_ratio": 2.4,
      "attention_seconds": 5340,
      "output_unlocked_seconds": 12816,
      "estimated_cost_usd": 3.208119,
      "has_unpriced_usage": false,
      "work_blocks": [
        {
          "id": "7c1d2f60-3e8b-4f2a-9d5c-1a6b8e0f4c22",
          "tool": "claude-code",
          "canonical_repo_name": "acme/checkout-service",
          "project_id": "b2a7f8d1-4c3e-4b9a-8f61-0d2e5c7a9b13",
          "project_display_name": "Checkout",
          "effective_started_at": "2026-08-09T09:14:02.318Z",
          "effective_ended_at": "2026-08-09T10:41:56.204Z",
          "effective_minutes": 87.9,
          "auto_minutes": 63.15,
          "active_intervals": [["2026-08-09T09:14:02.318Z", "2026-08-09T09:58:20.771Z"]],
          "tick_count": 96,
          "lines_added": 412,
          "lines_deleted": 187,
          "files_changed": 14,
          "tokens_input": 91480,
          "tokens_output": 26732,
          "tokens_cached": 512044,
          "tokens_reasoning": 8112,
          "model": "claude-sonnet-4-5",
          "model_provider": "anthropic",
          "estimated_cost_usd": 3.208119,
          "has_unpriced_usage": false,
          "streams": []
        }
      ]
    }
  ],
  "generated_at": "2026-08-09T14:30:11.582Z"
}

auto_minutes is active working time (agent turn intervals merged, capped at wall clock); tracked_in_window is wall-clock session time inside the requested day. streams lists AI-tool activity streams within the block (id, tool, label, timestamps, tick and token counts). Errors: 401, 500.

POST /get-time-breakdown

Tick-accurate hours over an arbitrary range, bucketed your way. This is the MCP get_time_breakdown tool.

Field	Type	Notes
`from` / `to`	string	`YYYY-MM-DD`; defaults: last 30 days ending today; max 366 days
`start_hour` / `end_hour`	integer	Local-hour window, 0–23 / 1–24; defaults 0 / 24; `end_hour` must exceed `start_hour`
`group_by`	string	`day`, `hour`, or `weekday`; default `hour`
`tz`	string	IANA zone; default profile timezone
`project`	string	Optional project filter (id, name, repo, or alias)

Response 200:

{
  "range": { "from": "2026-08-01", "to": "2026-08-07", "tz": "Europe/London" },
  "window": { "start_hour": 0, "end_hour": 24 },
  "group_by": "day",
  "project": { "id": "b2a7f8d1-4c3e-4b9a-8f61-0d2e5c7a9b13", "display_name": "Checkout" },
  "totals": { "hours": 31.7, "days_active": 6 },
  "buckets": [
    { "key": "2026-08-01", "hours": 6.2, "days_active": 1 },
    { "key": "2026-08-02", "hours": 4.9, "days_active": 1 }
  ],
  "generated_at": "2026-08-09T14:30:11.582Z"
}

Bucket keys are dates for day, local hours ("0"–"23") for hour, and lowercase day names for weekday. Errors: 400 validation or ambiguous project, 401, 404 unknown project, 405, 500.

POST /get-delivery-report

A per-project delivery rollup over a date range: tracked hours, sessions, commits with AI-authored share, merged PRs with line volume, tokens, and cost. This is the MCP get_delivery_report tool. Parameters: from, to, tz, project — same rules and defaults as get-time-breakdown.

Response 200:

{
  "range": { "from": "2026-07-10", "to": "2026-08-09", "tz": "Europe/London" },
  "project": { "id": "b2a7f8d1-4c3e-4b9a-8f61-0d2e5c7a9b13", "display_name": "Checkout" },
  "hours": { "tracked": 118.4, "days_active": 22 },
  "sessions": { "count": 47 },
  "commits": { "count": 96, "ai_authored": 41, "ai_share": 0.4271 },
  "prs": {
    "opened": 14,
    "merged": 12,
    "merged_line_volume": 8342,
    "merged_prs": [
      {
        "number": 218,
        "title": "Checkout retry flow",
        "repo": "acme/checkout-service",
        "merged_at": "2026-08-06T16:22:09Z",
        "line_volume": 1204
      }
    ]
  },
  "tokens": { "input": 1820441, "output": 410226, "cached": 9021584, "cache_write_5m": 122040, "cache_write_1h": 8120, "reasoning": 61240, "total": 11443655 },
  "cost": { "cost_usd": 84.31, "has_unpriced_usage": false },
  "generated_at": "2026-08-09T14:30:11.582Z"
}

tokens and cost are null when the range has no priced agent usage; merged_prs is capped at the 50 most recent. Errors: as get-time-breakdown.

POST /get-issue-report

Personal issue analytics over your synced Linear/Jira issues: effort per issue, cycle time, estimate variance, daily activity, and a size distribution. This is the MCP get_issue_report tool.

Field	Type	Notes
`from` / `to`	string	`YYYY-MM-DD`; default last 30 days; windows longer than 90 days are clamped
`issues_limit`	integer	1–100 issues in the detail list; default 25
`project`	string	Optional project filter

Response 200 (abridged):

{
  "project": null,
  "range": { "from": "2026-07-11", "to": "2026-08-09" },
  "totals": {
    "issue_count": 18,
    "touched_issue_count": 18,
    "completed_issue_count": 11,
    "active_minutes": 4120,
    "median_effort_minutes": 96,
    "median_cycle_minutes": 2870,
    "outlier_count": 2,
    "utilization_ratio": 0.64
  },
  "daily": [
    { "activity_date": "2026-08-08", "active_minutes": 212, "touched_issues": 3, "completed_issues": 1, "commit_count": 6 }
  ],
  "distribution": [
    { "band": "Tiny", "issue_count": 4, "active_minutes": 130 },
    { "band": "Small", "issue_count": 8, "active_minutes": 960 }
  ],
  "issues": [
    {
      "issue_key": "ENG-142",
      "provider": "linear",
      "title": "Fix login token refresh",
      "status": "Done",
      "estimate": 2,
      "actual_minutes": 148,
      "session_count": 3,
      "commit_count": 5,
      "cycle_minutes": 1910,
      "variance_percent": 23.3,
      "confidence": "confirmed"
    }
  ],
  "issues_page": { "limit": 25, "offset": 0, "total": 18, "has_more": false },
  "generated_at": "2026-08-09T14:30:11.582Z"
}

The full per-issue shape (tokens, cost, leverage, contributor counts, timestamps) is in the OpenAPI spec. Errors: 400 validation or ambiguous project, 401, 404 unknown project, 405, 500.

POST /get-insights

Your served weekly insights — the same cards shown on the Home page. This is the MCP get_insights tool.

Field	Type	Notes
`week_start`	string	Optional `YYYY-MM-DD` (a Monday) to fetch one specific week
`limit`	integer	1–12 most recent weeks; default 1

Response 200:

{
  "insights": [
    {
      "week_start": "2026-08-03",
      "status": "served",
      "items": [
        {
          "signal_id": "leverage_trend",
          "headline": "Your leverage doubled on Checkout",
          "body": "Agent-assisted sessions unlocked 2.4x output per attention hour, up from 1.1x the prior week."
        }
      ],
      "signals": null,
      "model": "claude-sonnet-4-5",
      "generated_at": "2026-08-04T06:00:12.007Z"
    }
  ],
  "generated_at": "2026-08-09T14:30:11.582Z"
}

Errors: 400 invalid week_start or limit, 401, 405, 500.

POST /get-user-projects

Your projects with repositories and rollup stats. This backs the MCP get_projects tool.

Field	Type	Notes
`include_stats`	boolean	Default true; set `false` for a fast bare list
`from_date` / `to_date`	string	`YYYY-MM-DD` stats window; default last 90 days

Response 200 (abridged):

{
  "projects": [
    {
      "id": "b2a7f8d1-4c3e-4b9a-8f61-0d2e5c7a9b13",
      "display_name": "Checkout",
      "canonical_repo_name": "acme/checkout-service",
      "aliases": ["checkout"],
      "sources": { "github": true, "vscode": true, "manual": true },
      "color": "#6366f1",
      "is_favorite": true,
      "is_enabled": true,
      "created_at": "2026-05-02T10:11:32.554Z",
      "updated_at": "2026-08-01T08:40:19.203Z",
      "repository_list": [
        { "id": "e9d4b7a2-6f10-4c58-9e33-71b0a8c5d4f6", "full_name": "acme/checkout-service", "enabled": true, "last_activity": "2026-08-08" }
      ],
      "stats": {
        "total_hours": 118.4,
        "total_commits": 96,
        "total_sessions": 47,
        "active_days": 22,
        "last_activity": "2026-08-08",
        "repositories": 1
      }
    }
  ]
}

Errors: 401, 500.