Usage Tags

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.

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 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:

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:

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 — plans, credits, and usage monitoring.
• Parse REST API Guide — full Parse endpoint reference.
• Extract REST API — full Extract endpoint reference.