Usage

Both plans are unlimited, so there is nothing to run out of. These endpoints tell you what ran and where. They keep their old field names so existing integrations do not break.

Current usage

GET /usage returns your plan (free or paid) and cost_estimates, the range of internal cost units for each action.

curl https://api.diagrams.so/api/v2/usage \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY"

credits_remaining is kept for compatibility and is always -1. It is not a balance. period_reset_at is null, because nothing resets.

Usage history

GET /usage/history returns an itemized, newest-first list of the tasks you ran (generate, edit, fix, re-layout), with the diagram and the surface that ran each one. It supports pagination and filters (action, source, diagram_id, livemode, from, to).

Response

{
  "items": [
    { "action_type": "generate", "credits_charged": 1, "diagram_id": "d_1a2b3c", "source": "api", "created_at": "2026-10-09T..." },
    { "action_type": "edit",     "credits_charged": 1, "diagram_id": "d_1a2b3c", "source": "mcp", "created_at": "2026-10-09T..." }
  ],
  "next_cursor": "...",
  "has_more": true,
  "summary": { "total_credits_charged": 2, "task_count": 2 }
}

source is one of api, sdk-python, sdk-ts, mcp, or web, so you can see where each task came from. credits_charged and summary.total_credits_charged are kept for compatibility: they report an internal cost figure, and nothing is billed or deducted.

Overview

Endpoints

Current usage

Usage history

​Current usage

​Usage history

Current usage

Usage history