---
title: Usage Tags | Developer Documentation
description: Attribute LlamaCloud API usage to teams, projects, environments, or customers by passing a Usage-Tags header on Parse and Extract requests (Enterprise).
---

Enterprise

Usage Tags let you attribute API usage to any dimension you care about — a team, a project, an environment, or an end customer. Pass a `Usage-Tags` header on your Parse and Extract requests and the tags flow all the way through to your usage metrics, so you can slice billing and consumption data however your organization needs.

This is useful when a single LlamaCloud organization serves many internal teams or downstream customers and you need to know who drove which usage — for chargeback, per-customer cost tracking, or separating production traffic from experimentation.

Note

Usage Tags are available on the **Enterprise** plan only. On other plans the `Usage-Tags` header is accepted but ignored, and no tags are recorded. To enable it, contact your account manager or [sales](https://www.llamaindex.ai/contact).

## How it works

1. Send a `Usage-Tags` request header on a Parse or Extract request.
2. LlamaCloud records the tags on every usage metric produced by that request.
3. Query [`GET /api/v1/beta/usage-metrics`](#reading-tags-back) and read the tags off the `usage_tags` field of each record.

## Sending tags

The `Usage-Tags` header takes a **comma-separated** list of tags. Each tag is a free-form string. A common convention is `key:value` (for example `team:data-platform`), but the values are opaque to LlamaCloud — use whatever scheme fits your reporting.

```
import httpx


client = httpx.Client(
    base_url="https://api.cloud.llamaindex.ai",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Usage-Tags": "team:data-platform,env:production",
    },
)


with open("report.pdf", "rb") as f:
    response = client.post(
        "/api/v2/parse/upload",
        files={"file": ("report.pdf", f, "application/pdf")},
    )
```

The same header works with `curl` and any HTTP client:

Terminal window

```
curl -X POST 'https://api.cloud.llamaindex.ai/api/v2/parse/upload' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H 'Usage-Tags: team:data-platform,env:production' \
  -F 'file=@report.pdf'
```

### Supported endpoints

Usage Tags are honored on **LlamaParse v2** and **LlamaExtract v2** job-creation requests:

| Product | Endpoints                                         |
| ------- | ------------------------------------------------- |
| Parse   | `POST /api/v2/parse`, `POST /api/v2/parse/upload` |
| Extract | `POST /api/v2/extract`                            |

## Limits

- **Up to 4 tags** per request.
- **Each tag ≤ 64 characters.**

A request that exceeds the maximum number of tags, or that contains a tag longer than 64 characters, is rejected with a `422 Unprocessable Entity` response. Trim your tags to stay within the limits.

## Reading tags back

Tags are attached to every usage metric the tagged request produces. Query the usage-metrics endpoint and read them off the `usage_tags` field:

Terminal window

```
curl 'https://api.cloud.llamaindex.ai/api/v1/beta/usage-metrics' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"
```

Each record carries the tags that were supplied on the originating request:

```
{
  "items": [
    {
      "id": "3f1c...",
      "event_type": "pages_parsed",
      "project_id": "project-uuid",
      "organization_id": "org-uuid",
      "value": 12,
      "credits": 30.0,
      "day": "2026-07-14",
      "usage_tags": ["team:data-platform", "env:production"]
    }
  ]
}
```

Group or filter these records by `usage_tags` in your own reporting to break down usage by team, environment, customer, or whatever dimension your tags encode. Metrics from untagged requests have a `null` `usage_tags` field.

## See also

- [Billing and Usage](/llamaparse/general/billing/index.md) — plans, credits, and usage monitoring.
- [Parse REST API Guide](/llamaparse/parse/guides/api-reference/index.md) — full Parse endpoint reference.
- [Extract REST API](/llamaparse/extract/api/index.md) — full Extract endpoint reference.