Administer

Usage API

Query credit and call usage programmatically.

All endpoints require start_time and end_time query parameters (ISO 8601). For authentication, see API overview.

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.