# Tags: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/tags
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 7.

## GET /v1/audio/tags

Operation id: `list_tags`

**List tags**

Returns every tag in your library with the number of files that carry it: the tags you added (`user_tags`, with their color) and the ones Scarleta suggested (`auto_tags`). Files in the trash are not counted. Counts against the hourly account request budget. Available to free and paid accounts.

Access: API key required; free and paid accounts. Cost: no token cost.

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `user_tags` | array<object> | Tags you put on files, most used first. |
| `user_tags[].name` | string |   |
| `user_tags[].count` | integer | Files that carry the tag. Allowed: -9007199254740991 to 9007199254740991. |
| `user_tags[].color` | string \| null | The color set for the tag, or null. |
| `user_tags[].similar_to` | array<string> | Other tags that differ only by letter case or surrounding spaces. |
| `auto_tags` | array<object> | Tags Scarleta suggested from analysis of your files, most used first. |
| `auto_tags[].name` | string |   |
| `auto_tags[].count` | integer | Allowed: -9007199254740991 to 9007199254740991. |

### Responses

200: Your tags.

```json
{
  "data": {
    "user_tags": [
      {
        "name": "morning",
        "count": 12,
        "color": "blue",
        "similar_to": []
      }
    ],
    "auto_tags": [
      {
        "name": "speech",
        "count": 40
      }
    ]
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: The tags could not be read. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl "https://api.scarleta.ai/v1/audio/tags" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```

## POST /v1/audio/tags

Operation id: `update_file_tags`

**Add or remove tags on files**

Adds the tags in `add` to, and removes the tags in `remove` from, every file in `audio_ids`, in one call. At most 50 tags per list, each at most 64 characters. A tag a file already has is not added twice, and a tag it does not have is ignored when removing. The response counts your files the call was applied to, including files that already had every tag to add and none of the tags to remove. Ids that are not your files are skipped without an error. If both lists are empty, or hold only empty strings, nothing is changed and `updated` is 0. Counts against the hourly account request budget. Available to free and paid accounts.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `audio_ids` | array<string> | Your files: library identifiers (`audio_id`) or storage identifiers (`file_id`). At least one. Allowed: at least 1 item. |
| `add` | array<string> | Tags to add, at most 50 of at most 64 characters each. Empty strings are ignored. |
| `remove` | array<string> | Tags to remove, at most 50 of at most 64 characters each. Empty strings are ignored. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `updated` | integer | Your files the call was applied to, whether or not their tags actually changed. Allowed: -9007199254740991 to 9007199254740991. |

### Responses

200: The number of your files the call was applied to. The body is `{ data }` without `meta`.

```json
{
  "data": {
    "updated": 2
  }
}
```

400: The body is empty or invalid JSON, `audio_ids` is missing or empty, a tag is too long, or a list has too many tags (`too_many_tags`).

```json
{
  "error": {
    "code": "tag_too_long",
    "message": "Tags must not exceed 64 characters",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#tag_too_long"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: The tags could not be saved. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_json`](https://www.scarleta.ai/docs/errors#invalid_json), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`invalid_tag`](https://www.scarleta.ai/docs/errors#invalid_tag), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_audio_ids`](https://www.scarleta.ai/docs/errors#missing_audio_ids), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`tag_too_long`](https://www.scarleta.ai/docs/errors#tag_too_long), [`too_many_audio_ids`](https://www.scarleta.ai/docs/errors#too_many_audio_ids), [`too_many_tags`](https://www.scarleta.ai/docs/errors#too_many_tags), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl -X POST "https://api.scarleta.ai/v1/audio/tags" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_bbb14949dc19"
    ],
    "add": [
      "morning",
      "demo"
    ],
    "remove": [
      "draft"
    ]
  }'
```

## POST /v1/audio/tags/adopt

Operation id: `adopt_auto_tag`

**Turn a suggested tag into your own**

Adds a tag Scarleta suggested (`auto_tags` in the tag list) to every file it was suggested for, as one of your own tags, optionally under another name (`as`). Files that already have the tag are not changed. A suggested tag that does not exist changes nothing and returns `updated: 0`. Counts against the hourly account request budget. Available to free and paid accounts.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `auto_tag` | string | The suggested tag, 1 to 64 characters. |
| `as` | string | The name to give it, 1 to 64 characters. Defaults to the suggested name. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `updated` | integer | Files whose tags changed. Allowed: -9007199254740991 to 9007199254740991. |

### Responses

200: The number of files that gained the tag.

```json
{
  "data": {
    "updated": 8
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The body is invalid JSON, or a name is empty or too long (`tag_too_long`).

```json
{
  "error": {
    "code": "invalid_tag",
    "message": "auto_tag must be a non-empty tag name",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_tag"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: The tag could not be adopted. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_json`](https://www.scarleta.ai/docs/errors#invalid_json), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`invalid_tag`](https://www.scarleta.ai/docs/errors#invalid_tag), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`tag_too_long`](https://www.scarleta.ai/docs/errors#tag_too_long), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl -X POST "https://api.scarleta.ai/v1/audio/tags/adopt" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_tag": "speech",
    "as": "talk"
  }'
```

## PUT /v1/audio/tags/color

Operation id: `set_tag_color`

**Set a tag color**

Sets the color of a tag, or clears it with `color: null`. The color is kept for the tag name even when no file carries it at the moment. Allowed colors: `red`, `orange`, `amber`, `green`, `teal`, `blue`, `purple`, `pink`, `gray`. Counts against the hourly account request budget. Available to free and paid accounts.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | The tag, 1 to 64 characters. |
| `color` | "red" \| "orange" \| "amber" \| "green" \| "teal" \| "blue" \| "purple" \| "pink" \| "gray" \| null | A color, or `null` to clear it. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `name` | string |   |
| `color` | string \| null |   |

### Responses

200: The tag and its color after the change.

```json
{
  "data": {
    "name": "morning",
    "color": "blue"
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The body is invalid JSON, the name is empty or too long, or the color is not an allowed one.

```json
{
  "error": {
    "code": "invalid_color",
    "message": "color must be null or one of: red, orange, amber, green, teal, blue, purple, pink, gray",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_color"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: The color could not be saved. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_color`](https://www.scarleta.ai/docs/errors#invalid_color), [`invalid_json`](https://www.scarleta.ai/docs/errors#invalid_json), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`invalid_tag`](https://www.scarleta.ai/docs/errors#invalid_tag), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`tag_too_long`](https://www.scarleta.ai/docs/errors#tag_too_long), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl -X PUT "https://api.scarleta.ai/v1/audio/tags/color" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "morning",
    "color": "blue"
  }'
```

## POST /v1/audio/tags/merge

Operation id: `merge_tags`

**Merge tags into one**

Replaces up to 20 tags with a single tag, on every file that carries any of them. If the target tag already has a color it keeps it; otherwise it takes the color of the first source that had one. The source tags disappear. Counts against the hourly account request budget. Available to free and paid accounts.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `from` | array<string> | Tags to merge, 1 to 20. |
| `into` | string | The tag to keep, 1 to 64 characters. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `updated` | integer | Files whose tags changed. Allowed: -9007199254740991 to 9007199254740991. |

### Responses

200: The number of files changed.

```json
{
  "data": {
    "updated": 5
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The body is invalid JSON, `from` is not 1 to the allowed number of names, or a name is empty or too long (`tag_too_long`).

```json
{
  "error": {
    "code": "invalid_tag",
    "message": "from must be an array of 1–20 tag names",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_tag"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: The tags could not be merged. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_json`](https://www.scarleta.ai/docs/errors#invalid_json), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`invalid_tag`](https://www.scarleta.ai/docs/errors#invalid_tag), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`tag_too_long`](https://www.scarleta.ai/docs/errors#tag_too_long), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl -X POST "https://api.scarleta.ai/v1/audio/tags/merge" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": [
      "demo",
      "draft"
    ],
    "into": "morning"
  }'
```

## POST /v1/audio/tags/rename

Operation id: `rename_tag`

**Rename a tag**

Renames a tag on every file that carries it. If a file already has the new name the two merge. The tag's color moves to the new name. Renaming a tag nothing carries changes nothing and returns `updated: 0`. Counts against the hourly account request budget. Available to free and paid accounts.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `from` | string | The tag to rename, 1 to 64 characters. |
| `to` | string | The new name, 1 to 64 characters. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `updated` | integer | Files whose tags changed. Allowed: -9007199254740991 to 9007199254740991. |

### Responses

200: The number of files changed.

```json
{
  "data": {
    "updated": 3
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The body is invalid JSON, or a name is empty, or too long (`tag_too_long`). `error.details.field` names it.

```json
{
  "error": {
    "code": "invalid_tag",
    "message": "to must be a non-empty tag name",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_tag"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: The tag could not be renamed. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_json`](https://www.scarleta.ai/docs/errors#invalid_json), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`invalid_tag`](https://www.scarleta.ai/docs/errors#invalid_tag), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`tag_too_long`](https://www.scarleta.ai/docs/errors#tag_too_long), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl -X POST "https://api.scarleta.ai/v1/audio/tags/rename" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "demo",
    "to": "draft-demo"
  }'
```

## POST /v1/audio/tags/selection-state

Operation id: `get_tag_selection_state`

**Count tags across a selection of files**

For the files you name, returns each tag they carry with how many of those files carry it, so a tag that is on all of them can be told from one that is on some. Files that are not yours, and files in the trash, are left out. Counts against the hourly account request budget. Available to free and paid accounts.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `audio_ids` | array<string> | The selection: library identifiers (`audio_id`) or storage identifiers (`file_id`) of your files, 1 to 5000. |

### Responses

200: Tag counts for the selection. An empty object when no tag applies.

```json
{
  "data": {
    "morning": 2,
    "demo": 1
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The `audio_ids` list is missing, empty, or not a list of strings.

```json
{
  "error": {
    "code": "missing_audio_ids",
    "message": "audio_ids must be a non-empty array of strings",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#missing_audio_ids"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: The tags could not be read. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_json`](https://www.scarleta.ai/docs/errors#invalid_json), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_audio_ids`](https://www.scarleta.ai/docs/errors#missing_audio_ids), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`too_many_audio_ids`](https://www.scarleta.ai/docs/errors#too_many_audio_ids), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl -X POST "https://api.scarleta.ai/v1/audio/tags/selection-state" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_bbb14949dc19"
    ]
  }'
```