> This page is for Agent Handler.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Usage API

> REST endpoints for querying Agent Handler usage by organization and by Registered User, including per-tool breakdowns.

All endpoints require `start_time` and `end_time` query parameters (ISO 8601). For authentication, see [API overview](/merge-agent-handler/agent-handler).

The window between them cannot exceed 31 days, and `start_time` cannot be more than 90 days in the past. A request that breaks either limit is rejected rather than silently truncated, so if you report on a longer period, page through it 31 days at a time and accumulate the totals yourself. `end_time` has to be in the past, and both bounds are floored to the hour.

## GET /api/v1/usage/

Returns total credit and call usage for the organization.

```json
{
  "total_credits_used": 500,
  "total_call_count": 2100,
  "last_updated_at": "2026-06-03T17:00:00Z"
}
```

## GET /api/v1/usage/registered-users/

Returns credit and call usage broken down per Registered User. Paginated. 50 rows per page by default, up to 100 with `page_size`.

```json
{
  "count": 128,
  "next": "https://ah-api.merge.dev/api/v1/usage/registered-users/?page=2",
  "previous": null,
  "last_updated_at": "2026-06-03T17:00:00Z",
  "results": [
    {
      "registered_user_id": "uuid",
      "credits_used": 250,
      "call_count": 1050
    }
  ]
}
```

Registered Users with no usage in the window don't appear at all, so the row count tracks who was active, not how many users you have.

## GET /api/v1/usage/registered-users/\{registered_user_id}/

Returns a full tool-level breakdown for a single Registered User. Useful for surfacing action-level telemetry such as emails sent or Slack messages posted.

```json
{
  "registered_user_id": "uuid",
  "total_credits_used": 250,
  "total_call_count": 1050,
  "last_updated_at": "2026-06-03T17:00:00Z",
  "tool_breakdown": [
    {
      "connector": "gmail",
      "connector_id": "uuid",
      "tool_name": "gmail__send_email",
      "credit_type": "SIMPLE",
      "credits_used": 100,
      "call_count": 47
    },
    {
      "connector": "slack",
      "connector_id": "uuid",
      "tool_name": "slack__send_message",
      "credit_type": "SIMPLE",
      "credits_used": 50,
      "call_count": 12
    }
  ]
}
```

`connector` is the Connector's slug, and `connector_id` its UUID - prefer the slug, which is stable and readable. `credit_type` is `SIMPLE` or `COMPLEX`. A Registered User with no usage in the window comes back `404` rather than an empty breakdown, so read that as "no usage" rather than "no such user".

## GET /api/v1/usage/tools/

Returns one row per Connector and tool, summed across every Registered User and credit type, ordered by credits used. Paginated. Reach for this one when the question is which tools are driving spend rather than which people are.

```json
{
  "count": 42,
  "next": "https://ah-api.merge.dev/api/v1/usage/tools/?page=2",
  "previous": null,
  "last_updated_at": "2026-06-03T17:00:00Z",
  "results": [
    {
      "connector": "linear",
      "tool_name": "linear__create_issue",
      "credits_used": 4210,
      "call_count": 980
    }
  ]
}
```

`tool_name` is fully qualified, the same string an agent passes to `tools/call`. `connector` is `null` for meta-tool usage, which belongs to no Connector. `last_updated_at` is when the aggregation last ran, so calls made since then are not counted yet.