跳至主要內容

支出追蹤

追蹤跨越 100+ LLM 的金鑰、使用者與團隊支出。

LiteLLM 會自動追蹤所有已知模型的支出。請參閱我們的 模型成本對照表

當回應包含分級中繼資料時，會自動套用特定提供者的成本追蹤（例如 Vertex AI PayGo / priority pricing、Bedrock service tiers、Azure base model mapping）。

保持定價資料為最新

從 GitHub 同步模型定價資料，以確保成本追蹤準確。

成本與您的提供者帳單不符？

請使用 Debugging a cost discrepancy 中的逐步流程：對齊時間範圍、比較 token 類別（包含快取），然後判定差異是來自 ingestion、公式，還是 model-map 定價。

如何使用 LiteLLM 追蹤支出​

步驟 1

👉 使用資料庫設定 LiteLLM

步驟2 傳送 /chat/completions 請求

Send Request with Spend Tracking
import openai
client = openai.OpenAI(
    api_key="sk-1234",
    base_url="http://0.0.0.0:4000"
)

response = client.chat.completions.create(
    model="llama3",
    messages = [
        {
            "role": "user",
            "content": "this is a test request, write a short poem"
        }
    ],
    user="palantir", # OPTIONAL: pass user to track spend by user
    extra_body={
        "metadata": {
            "tags": ["jobID:214590dsff09fds", "taskName:run_page_classification"] # ENTERPRISE: pass tags to track spend by tags
        }
    }
)

print(response)

步驟3 - 驗證支出已被追蹤 就是這樣。現在請驗證您的支出是否已被追蹤

預期會在回應標頭中看到 x-litellm-response-cost，以及計算出的成本

允許非 Proxy 管理員存取 /spend 端點​

當您希望非 proxy 管理員可存取 /spend 端點時使用此功能

資訊

安排與我們會議以取得您的 Enterprise License 與我們安排會議以取得您的 Enterprise License

建立金鑰​

使用 permissions={"get_spend_routes": true} 建立金鑰

Generate Key with Spend Route Permissions
curl --location 'http://0.0.0.0:4000/key/generate' \
        --header 'Authorization: Bearer sk-1234' \
        --header 'Content-Type: application/json' \
        --data '{
            "permissions": {"get_spend_routes": true}
    }'
在 /spend 端點使用產生的金鑰​

使用新產生的金鑰存取支出路由

curl -X GET 'http://localhost:4000/global/spend/report?start_date=2024-04-01&end_date=2024-06-30' \
  -H 'Authorization: Bearer sk-H16BKvrSNConSsBYLGc_7A'

重設團隊、API 金鑰支出 - 僅限 MASTER KEY​

若您想要，請使用 /global/spend/reset：

  • 重設所有 API 金鑰、團隊的支出。所有團隊與金鑰在 LiteLLM_TeamTable 與 LiteLLM_VerificationToken 中的 spend 將被設為 spend=0

  • LiteLLM 會保留 LiteLLMSpendLogs 中的所有記錄以供稽核

請求​

只有您設定的 LITELLM_MASTER_KEY 可以存取此路由

curl -X POST \
  'http://localhost:4000/global/spend/reset' \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json'
預期回應​
{"message":"Spend for all API Keys and Teams reset successfully","status":"success"}

每位使用者的總支出​

假設您已為終端使用者發放金鑰，並在金鑰上設定其 user_id，您可以查看他們的用量。

Get User Spend - API Request
curl -L -X GET 'http://localhost:4000/user/info?user_id=jane_smith' \
-H 'Authorization: Bearer sk-...'
Total for a user API Response
{
  "user_id": "jane_smith",
  "user_info": {
    "spend": 0.1
  },
  "keys": [
    {
      "token": "6e952b0efcafbb6350240db25ed534b4ec6011b3e1ba1006eb4f903461fd36f6",
      "key_name": "sk-...KE_A",
      "key_alias": "user-01882d6b-e090-776a-a587-21c63e502670-01983ddb-872f-71a3-8b3a-f9452c705483",
      "soft_budget_cooldown": false,
      "spend": 0.1,
      "expires": "2025-07-31T19:14:13.968000+00:00",
      "models": [],
      "aliases": {},
      "config": {},
      "user_id": "01982d6b-e090-776a-a587-21c63e502660",
      "team_id": "f2044fde-2293-482f-bf35-a8dab4e85c5f",
      "permissions": {},
      "max_parallel_requests": null,
      "metadata": {},
      "blocked": null,
      "tpm_limit": null,
      "rpm_limit": null,
      "max_budget": null,
      "budget_duration": null,
      "budget_reset_at": null,
      "allowed_cache_controls": [],
      "allowed_routes": [],
      "model_spend": {},
      "model_max_budget": {},
      "budget_id": null,
      "organization_id": null,
      "object_permission_id": null,
      "created_at": "2025-07-24T19:14:13.970000Z",
      "created_by": "582b168f-fc11-4e14-ad6a-cf4bb3656ddc",
      "updated_at": "2025-07-24T19:14:13.970000Z",
      "updated_by": "582b168f-fc11-4e14-ad6a-cf4bb3656ddc",
      "litellm_budget_table": null,
      "litellm_organization_table": null,
      "object_permission": null,
      "team_alias": null
    }
  ],
  "teams": []
}

警告 終端使用者可以在其請求本文中提供 user 參數；如此一來，透過 /customer/info?end_user_id=self-declared-user 報告的成本會增加到該參數所指定的使用者，而不是該 API 所回報的金鑰擁有者。這表示使用者可能會透過他們的方法「避免」其支出被追蹤。 這表示如果您需要追蹤使用者支出，且有發放 API 金鑰給終端使用者，您必須在建立其 API 金鑰時一律設定 user_id，並且每次代表他們在後端服務中進行 LLM 呼叫時，都使用為該使用者發放的金鑰。這樣才能追蹤他們的支出。

支出清單端點（/spend/keys 與 /spend/users）​

這些端點會列出 verification-token 與 user 表中的資料列（依支出排序）。它們包含在 spend_tracking_routes 中，供內部使用者使用。

存取控制（預設）​

預設情況下，非管理員呼叫者會限定在自己的資料範圍內：

呼叫者角色/spend/keys/spend/users
proxy_admin / proxy_admin_viewer所有金鑰所有使用者（或單一資料列的 ?user_id=）
internal_user / internal_user_view_onlyuser_id 與呼叫者相符的金鑰只有呼叫者自己的資料列
未在金鑰上設定 user_id 的非管理員空清單 []空清單 []

內部使用者若為另一位使用者傳遞 ?user_id=，會收到 HTTP 403（而不是被靜默過濾的清單）。

Admin — all keys
curl -X GET 'http://localhost:4000/spend/keys' \
  -H 'Authorization: Bearer <proxy-admin-key>'
Internal user — own keys only
curl -X GET 'http://localhost:4000/spend/keys' \
  -H 'Authorization: Bearer <internal-user-key>'

舊版未限定範圍行為（升級路徑）​

在這個範圍限定變更之前，任何已驗證的金鑰都可以列出完整的金鑰／使用者表。如果您依賴該行為（例如使用 internal_user 金鑰的自動化），請明確選擇退出：

config.yaml
general_settings:
  legacy_unscoped_spend_list_endpoints: true

或者設定環境變數：

export LITELLM_LEGACY_UNSCOPED_SPEND_LIST_ENDPOINTS=true

啟用舊版模式後，/spend/keys 與 /spend/users 對非管理員呼叫者的行為會與先前相同。

若要在不使用舊版旗標名稱的情況下停用範圍限定：

general_settings:
  scope_spend_list_endpoints_to_caller: false

請參閱 general_settings 參考文件 以了解 scope_spend_list_endpoints_to_caller 與 legacy_unscoped_spend_list_endpoints。

資訊

針對每位使用者的支出分析，請優先使用 /user/info?user_id=... 或 /global/spend/report。這些清單端點是為管理員儀表板與已限定範圍的自助式檢視而設計。

每日支出明細 API​

透過單一端點擷取使用者的細粒度每日用量資料（按模型、提供者與 API 金鑰）。

範例請求：

Daily Spend Breakdown API
curl -L -X GET 'http://localhost:4000/user/daily/activity?start_date=2025-03-20&end_date=2025-03-27' \
-H 'Authorization: Bearer sk-...'
Daily Spend Breakdown API Response
{
    "results": [
        {
            "date": "2025-03-27",
            "metrics": {
                "spend": 0.0177072,
                "prompt_tokens": 111,
                "completion_tokens": 1711,
                "total_tokens": 1822,
                "api_requests": 11
            },
            "breakdown": {
                "models": {
                    "gpt-4o-mini": {
                        "spend": 1.095e-05,
                        "prompt_tokens": 37,
                        "completion_tokens": 9,
                        "total_tokens": 46,
                        "api_requests": 1
                },
                "providers": { "openai": { ... }, "azure_ai": { ... } },
                "api_keys": { "3126b6eaf1...": { ... } }
            }
        }
    ],
    "metadata": {
        "total_spend": 0.7274667,
        "total_prompt_tokens": 280990,
        "total_completion_tokens": 376674,
        "total_api_requests": 14
    }
}

API 參考​

請參閱我們的 Swagger API 以取得關於 /user/daily/activity 端點的更多詳細資訊

自訂標籤​

查看完整請求標籤文件

如需涵蓋所有標籤選項的完整文件，包括 x-litellm-tags 標頭、請求本文 tags 與以設定為基礎的標籤，請參閱專門的 Request Tags 頁面。

需求：

  • Virtual Keys 與資料庫應已設定，請參閱 virtual keys

注意： 預設情況下，LiteLLM 會將 User-Agent 作為支出追蹤的自訂標籤進行追蹤。這可讓您檢視 Claude Code、Gemini CLI 等工具的用量。

用戶端支出標籤​

curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "metadata": {
        "tags": ["tag1", "tag2", "tag3"]
    }
}

'

新增自訂標頭以進行支出追蹤​

您可以在請求中新增自訂標頭，以追蹤支出與用量。

litellm_settings:
  extra_spend_tag_headers:
    - "x-custom-header"

停用 user-agent 追蹤​

您可以將 litellm_settings.disable_add_user_agent_to_request_tags 設為 true 來停用 user-agent 追蹤。

litellm_settings:
  disable_add_user_agent_to_request_tags: true

✨（Enterprise）產生支出報告​

用於向其他團隊、客戶、使用者收費

使用 /global/spend/report 端點取得支出報告

範例請求​

👉 金鑰變更：指定 group_by=team

curl -X GET 'http://localhost:4000/global/spend/report?start_date=2024-04-01&end_date=2024-06-30&group_by=team' \
  -H 'Authorization: Bearer sk-1234'

範例回應​

[
    {
        "group_by_day": "2024-04-30T00:00:00+00:00",
        "teams": [
            {
                "team_name": "Prod Team",
                "total_spend": 0.0015265,
                "metadata": [ # see the spend by unique(key + model)
                    {
                        "model": "gpt-4",
                        "spend": 0.00123,
                        "total_tokens": 28,
                        "api_key": "88dc28.." # the hashed api key
                    },
                    {
                        "model": "gpt-4",
                        "spend": 0.00123,
                        "total_tokens": 28,
                        "api_key": "a73dc2.." # the hashed api key
                    },
                    {
                        "model": "chatgpt-v-2",
                        "spend": 0.000214,
                        "total_tokens": 122,
                        "api_key": "898c28.." # the hashed api key
                    },
                    {
                        "model": "gpt-3.5-turbo",
                        "spend": 0.0000825,
                        "total_tokens": 85,
                        "api_key": "84dc28.." # the hashed api key
                    }
                ]
            }
        ]
    }
]

📊 支出記錄 API - 個別交易記錄​

/spend/logs 端點現在支援 summarize 參數，以在使用日期篩選器時控制資料格式。

主要參數​

參數說明
summarize新參數：true（預設）= 彙總資料，false = 個別交易記錄

範例​

取得個別交易記錄：

Get Individual Transaction Logs
curl -X GET "http://localhost:4000/spend/logs?start_date=2024-01-01&end_date=2024-01-02&summarize=false" \
-H "Authorization: Bearer sk-1234"

取得彙總資料（預設）：

Get Summarized Spend Data
curl -X GET "http://localhost:4000/spend/logs?start_date=2024-01-01&end_date=2024-01-02" \
-H "Authorization: Bearer sk-1234"

使用情境：

  • summarize=false：分析儀表板、ETL 處理流程、詳細稽核軌跡
  • summarize=true：每日支出報告、高層級成本追蹤（舊行為）

✨ 自訂支出記錄中繼資料​

將特定 key,value 配對作為支出記錄中繼資料的一部分進行記錄

資訊

在支出記錄中繼資料中記錄特定 key,value 配對是企業版功能。

需求：

  • 需要先設定 Virtual Keys 與資料庫，請參閱 virtual keys

用法 - 具有特殊支出記錄中繼資料的 /chat/completions 請求​

curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "metadata": {
      "spend_logs_metadata": {
          "hello": "world"
      }
    }
}

'

檢視含自訂中繼資料的支出​

/spend/logs 請求格式​

curl -X GET "http://0.0.0.0:4000/spend/logs?request_id=<your-call-id" \ # e.g.: chatcmpl-9ZKMURhVYSi9D6r6PJ9vLcayIK0Vm
-H "Authorization: Bearer sk-1234"

/spend/logs 回應格式​

[
    {
        "request_id": "chatcmpl-9ZKMURhVYSi9D6r6PJ9vLcayIK0Vm",
        "call_type": "acompletion",
        "metadata": {
            "user_api_key": "example-api-key-123",
            "user_api_key_alias": null,
            "spend_logs_metadata": { # 👈 LOGGED CUSTOM METADATA
                "hello": "world"
            },
            "user_api_key_team_id": null,
            "user_api_key_user_id": "116544810872468347480",
            "user_api_key_team_alias": null
        },
    }
]
🚅
LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →