> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnichar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage of licensed characters

> Read every generation, block and download of a licensed Omnichar character, with filters, cursor pagination and totals, and receive usage webhooks.

Every license check is recorded: each run and download with a [licensed character](https://docs.omnichar.org/api/licensed-characters.md), 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`.

```bash theme={null}
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. |

```json theme={null}
{
  "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](https://docs.omnichar.org/api/errors.md#license-checks).

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](https://docs.omnichar.org/api/webhooks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.