Enterprise

Usage Tags 让你能把 API 用量归属到你在意的任何维度 —— 一个团队、一个 project、一个环境，或一个终端客户。在 Parse 与 Extract 请求上带一个 Usage-Tags 头，这些标签就会一路流进你的用量指标，于是你可以按组织需要的方式任意切分账单与消耗数据。

当一个 LlamaCloud 组织要服务很多内部团队或下游客户、而你需要知道是谁产生了哪部分用量时，这很有用 —— 用于成本回溯、按客户跟踪成本，或把生产流量与实验流量分开。

注意

Usage Tags 仅在 Enterprise 套餐上可用。其他套餐上 Usage-Tags 头会被接受但忽略，不记录任何标签。要启用它，请联系你的客户经理或销售。

工作原理

1. 在 Parse 或 Extract 请求上发送 Usage-Tags 请求头。
2. LlamaCloud 会把标签记录到该请求产生的每一项用量指标上。
3. 查询 GET /api/v1/beta/usage-metrics，从每条记录的 usage_tags 字段读出标签。

发送标签

Usage-Tags 头接受一个逗号分隔的标签列表。每个标签是一个自由格式的字符串。常见约定是 key:value（例如 team:data-platform），但对 LlamaCloud 而言这些取值是不透明的 —— 按你的报表需要选方案即可。

下面的示例都在一份样张报告上跑 Parse 任务。先把美国财政部 FY2024 财报的执行摘要下载为 report.pdf：

终端窗口

curl -fL -o report.pdf https://fiscal.treasury.gov/system/files/files/reports-statements/financial-report/2024/executive-summary-2024.pdf

所有 LlamaCloud SDK 都允许你在 client 上一次性设好这个头，于是它发出的每个请求都带着标签：

• Python
• TypeScript
• Go
• Java

from llama_cloud import LlamaCloud

client = LlamaCloud(
    default_headers={"Usage-Tags": "team:data-platform,env:production"},
)

with open("report.pdf", "rb") as f:
    job = client.parsing.create(
        upload_file=f,
        tier="agentic",
        version="latest",
    )

print(job.id)

import LlamaCloud from '@llamaindex/llama-cloud';
import fs from 'fs';

const client = new LlamaCloud({
    defaultHeaders: { 'Usage-Tags': 'team:data-platform,env:production' },
});

const job = await client.parsing.create({
    upload_file: fs.createReadStream('report.pdf'),
    tier: 'agentic',
    version: 'latest',
});

console.log(job.id);

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    llamacloud "github.com/run-llama/llama-parse-go"
    "github.com/run-llama/llama-parse-go/option"
)

func main() {
    ctx := context.Background()
    client := llamacloud.NewClient(
        option.WithHeader("Usage-Tags", "team:data-platform,env:production"),
    )

    f, err := os.Open("report.pdf")
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()

    file, err := client.Files.New(ctx, llamacloud.FileNewParams{
        File:    f,
        Purpose: "parse",
    })
    if err != nil {
        log.Fatal(err)
    }

    job, err := client.Parsing.New(ctx, llamacloud.ParsingNewParams{
        FileID:  llamacloud.String(file.ID),
        Tier:    llamacloud.ParsingNewParamsTierAgentic,
        Version: llamacloud.ParsingNewParamsVersionLatest,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(job.ID)
}

import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;
import ai.llamaindex.llamacloud.models.files.FileCreateParams;
import ai.llamaindex.llamacloud.models.files.FileCreateResponse;
import ai.llamaindex.llamacloud.models.parsing.ParsingCreateParams;
import ai.llamaindex.llamacloud.models.parsing.ParsingCreateResponse;
import java.nio.file.Paths;

public class UsageTagsExample {
    public static void main(String[] args) throws Exception {
        LlamaCloudClient client = LlamaCloudOkHttpClient.builder()
            .fromEnv()
            .putHeader("Usage-Tags", "team:data-platform,env:production")
            .build();

        FileCreateResponse file = client.files().create(
            FileCreateParams.builder()
                .file(Paths.get("report.pdf"))
                .purpose("parse")
                .build());

        ParsingCreateResponse job = client.parsing().create(
            ParsingCreateParams.builder()
                .fileId(file.id())
                .tier(ParsingCreateParams.Tier.AGENTIC)
                .version(ParsingCreateParams.Version.LATEST)
                .build());

        System.out.println(job.id());
    }
}

同一个头也能用在 curl 与任何 HTTP 客户端上：

终端窗口

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'

支持的端点

Usage Tags 会在 LlamaParse v2 与 LlamaExtract v2 的任务创建请求上生效：

产品	端点
Parse	POST /api/v2/parse、POST /api/v2/parse/upload
Extract	POST /api/v2/extract

限制

• 每个请求最多 4 个标签。
• 每个标签 ≤ 64 字符。

标签数超过上限、或某个标签长于 64 字符的请求，会以 422 Unprocessable Entity 拒绝。请精简标签以留在限制之内。

把标签读回来

标签会附加在被标记请求产生的每一项用量指标上。查询 usage-metrics 端点，从 usage_tags 字段读出即可：

终端窗口

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

每条记录都带着发起请求时提供的那些标签：

{
  "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"]
    }
  ]
}

在你自己的报表里按 usage_tags 对这些记录分组或过滤，就能按团队、环境、客户，或你的标签所编码的任意维度拆分用量。未被标记的请求，其指标的 usage_tags 字段为 null。

另请参阅

• 计费与用量 —— 套餐、credit 与用量监控。
• Parse REST API 指南 —— Parse 端点完整参考。
• Extract REST API —— Extract 端点完整参考。