Usage of licensed characters

Every license check is recorded: each run and download with a licensed character, allowed or blocked. When an allowed run finishes, its record gets the number of outputs, their SHA-256 hashes and the credits charged.

Reading usage

Call	Who	Shows
`GET /v1/licenses/{key}/usage`	The provider and the licensee	The provider sees everything under the license; the licensee sees its own records.
`GET /v1/chars/{id}/usage`	The provider	Every record for the character: each licensee’s and the provider’s own runs.

Both need the usage:read scope. Anyone else gets 404.

curl -s "https://api.omnichar.org/v1/licenses/$LICENSE_KEY/usage?from=2026-11-01&result=allowed&limit=50" \
  -H "Authorization: Bearer $OMNICHAR_API_KEY"

Query	Meaning
`from`, `to`	A date (`2026-11-01`, the whole day) or a timestamp. `to` is exclusive for a timestamp.
`result`	`allowed` or `blocked`.
`media`	`image`, `video`, `voice`, or `char` for downloads.
`surface`	`cloud`, `api`, `app` or `download`.
`limit`	1 to 200, default 50.
`cursor`	`next_cursor` from the previous page.

{
  "items": [
    {
      "id": "c1d2...",
      "env": "production",
      "license_key": "lic_live_Q2x8...",
      "char_id": "7f1c2a9e-...",
      "team_id": "91aa...",
      "provider_team_id": "2c0d...",
      "surface": "api",
      "media": "image",
      "use": "advertising",
      "territory": "SE",
      "result": "allowed",
      "reason": null,
      "run_id": "0b6e...",
      "output_count": 1,
      "output_hashes": ["3f5a..."],
      "credits_charged": 2,
      "created_at": "2026-11-10T09:12:44.000Z",
      "updated_at": "2026-11-10T09:13:20.000Z"
    }
  ],
  "next_cursor": "eyJ0Ijoi...",
  "totals": { "allowed": 41, "blocked": 6, "outputs": 88, "downloads": 2 },
  "days": [{ "day": "2026-11-10", "allowed": 4, "blocked": 1, "outputs": 9 }]
}

Items are newest first. totals and days cover every record that matches the filters, across all pages: allowed counts runs, outputs sums their outputs, blocked counts refused runs and downloads, and downloads counts .char downloads. days has one entry per UTC day with any records. team_id is the team that ran it; license_key is null on the provider’s own runs. reason is one of the license check reasons. In Omnichar Cloud the same report is the Usage section on a protected character’s page for the provider, and on a licensed character’s page for the licensee, with a daily chart and a CSV export.

Usage webhooks

Event	Sent to	When
`usage.generated`	The provider, for every team’s runs; the licensee, for its own	An allowed run finished, with its outputs and hashes.
`usage.blocked`	The provider	A license check refused a run or a download.

data is a usage record in the shape above. Add the events to an endpoint under Settings → Webhooks; see Webhooks.

Get started

Omnichar Cloud

Omnichar Studio

ComfyUI node

API

API reference

Integrations

Usage of licensed characters

Reading usage

Usage webhooks