# Retrieve an asset's usage

Source: https://kirora.io/docs/api/reference/getAssetUsage

`GET /v1/assets/{id}/usage`

Requires an API key with the `templates:read` scope. [About keys and scopes](https://kirora.io/docs/api/reference/authentication)

Works with integration, agent and partner keys.

Everything whose content contains the file's address, found by the asset id it carries, so raw HTML, CSS `url(...)` and addresses with a query string count: templates (the draft or any published version), shared blocks, campaigns and journeys in any status, journey enrollments in progress, unsent transactional messages, and the workspace brand, each list at most 50 long, with `hasMore` when one is longer. Deleting the asset is refused while any of these is listed. Each entry says whether it is `locked`: one that no edit or delete can free (a sent campaign, an ended journey, enrollments under way, a message about to go) keeps the image, and its bytes count toward storage, until that use ends, if ever.

## Path parameters

- `id` (string, required, uuid) — The asset's id.

## Header parameters

- `Kirora-Workspace` (string, optional, pattern `^[A-Za-z0-9._:-]{1,128}$`) — Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

## Returns

Returns `200 OK` with an `AssetUsage` in `data`. Otherwise returns an error; [Errors](https://kirora.io/docs/api/reference/errors) lists every code and which to retry.

- `templates` (object[], required) — Templates whose draft or any published version uses the image.
  - `id` (string, required, uuid)
  - `name` (string, required)
  - `locked` (boolean, required) — True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.
- `sharedBlocks` (object[], required) — Shared blocks that use the image.
  - `id` (string, required, uuid)
  - `name` (string, required)
  - `locked` (boolean, required) — True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.
- `campaigns` (object[], required) — Campaigns, sent or not, that use the image; locked once sending has started.
  - `id` (string, required, uuid)
  - `name` (string, required)
  - `locked` (boolean, required) — True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.
- `journeys` (object[], required) — Journeys, in any status, whose steps use the image; locked once ended.
  - `id` (string, required, uuid)
  - `name` (string, required)
  - `locked` (boolean, required) — True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.
- `journeysWithEnrollments` (object[], required) — Journeys with enrollments in progress that follow steps using the image. An enrollment keeps the steps it started with, so these free the image only when those enrollments finish.
  - `id` (string, required, uuid)
  - `name` (string, required)
  - `locked` (boolean, required) — True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.
- `messages` (object[], required) — Transactional messages not yet sent that use the image; `name` is the subject or title. A timed one can be cancelled; an immediate one is locked.
  - `id` (string, required, uuid)
  - `name` (string, required)
  - `locked` (boolean, required) — True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.
- `brandKit` (boolean, required) — Whether it is the workspace's brand kit logo.
- `hasMore` (boolean, required) — More use it than are listed: each list stops at 50.

## Example

```bash
curl https://api.kirora.io/v1/assets/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": {
    "templates": [
      {
        "id": "0192f3d0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "name": "Welcome email",
        "locked": false
      }
    ],
    "sharedBlocks": [],
    "campaigns": [
      {
        "id": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
        "name": "October newsletter",
        "locked": true
      }
    ],
    "journeys": [],
    "journeysWithEnrollments": [],
    "messages": [],
    "brandKit": false,
    "hasMore": false
  }
}
```