> ## Documentation Index > Fetch the complete documentation index at: https://friendli.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Usage and Costs > Retrieve team-level usage and cost data through the Friendli Suite API. Covers authentication, rate limits, and practical examples with cURL. Friendli Suite exposes two administration endpoints that let you track consumption programmatically: * **Cost** (`GET /v1/team/cost`) — rated dollar amounts for your team, grouped by billing line item. * **Usage** (`GET /v1/team/usage`) — metered quantities such as token counts and GPU time, with filters by model, product type, and user. Use the cost endpoint when you need dollar figures. Use the usage endpoint when you need raw consumption numbers — for example, to build a dashboard, do chargeback accounting, or compare token volume across models. ## Authentication Both endpoints require a **Personal API Key** (for example, `flp_XXX`) passed as a bearer token in the `Authorization` header. If you do not already have one, generate it from **[Friendli Suite > Personal Settings > API Keys](https://friendli.ai/suite/~/setting/keys)**. For the full steps, see the [Personal API Keys](/docs/guides/suite/personal-api-keys) guide. ```bash theme={null} export FRIENDLIAI_API_KEY="" ``` ### Specifying a Team To target a specific team, pass the team ID in the `X-Friendli-Team` header. Omit it to use your default team. ```bash theme={null} curl https://api.friendli.ai/v1/team/cost \ -H "Authorization: Bearer $FRIENDLIAI_API_KEY" \ -H "X-Friendli-Team: " ``` ## Rate Limits and Polling Both endpoints return `429` if you call them too frequently. Wait at least 5 minutes between repeated calls. ## Cost API `GET /v1/team/cost` returns daily cost buckets for a time range you specify. Each bucket contains the total cost in USD and, when grouped by line item, a breakdown by billing category. ### Parameters | Parameter | Type | Required | Description | | ----------------- | ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `start_time` | string (date-time) | Yes | RFC 3339 timestamp in UTC. The time portion must be zeroed out (for example, `2026-01-01T00:00:00Z`). No earlier than one year ago. | | `end_time` | string (date-time) | Yes | RFC 3339 timestamp in UTC, zeroed out. Must not be later than midnight UTC of the next day. | | `bucket_width` | string | No | Width of each time bucket. Only `1d` is supported. Defaults to `1d`. | | `limit` | integer | No | Number of buckets to return. Range 1–35, default 7. | | `page` | string | No | Pagination cursor from the `next_page` field of a previous response. | | `group_by` | string | No | Group costs by field. Only `line_item` is supported. | | `X-Friendli-Team` | string (header) | No | Team ID to run the request as. | ### Example: Get Daily Cost Totals ```bash theme={null} curl --request GET \ --url "https://api.friendli.ai/v1/team/cost?start_time=2026-06-01T00:00:00Z&end_time=2026-06-08T00:00:00Z" \ --header "Authorization: Bearer $FRIENDLIAI_API_KEY" ``` ```json expandable theme={null} { "has_more": false, "next_page": null, "data": [ { "start_time": "2026-06-01T00:00:00Z", "end_time": "2026-06-02T00:00:00Z", "results": [ { "total": "67.89123016" } ] }, { "start_time": "2026-06-02T00:00:00Z", "end_time": "2026-06-03T00:00:00Z", "results": [ { "total": "87.2309217066666666" } ] } ] } ``` ### Example: Cost Broken Down by Line Item Pass `group_by=line_item` to see which billing categories drove the cost. ```bash theme={null} curl --request GET \ --url "https://api.friendli.ai/v1/team/cost?start_time=2026-06-01T00:00:00Z&end_time=2026-06-08T00:00:00Z&group_by=line_item" \ --header "Authorization: Bearer $FRIENDLIAI_API_KEY" ``` ```json expandable theme={null} { "has_more": false, "next_page": null, "data": [ { "start_time": "2026-06-01T00:00:00Z", "end_time": "2026-06-02T00:00:00Z", "results": [ { "total": "0.3575", "quantity": "0.09166666666666666", "unit_price": "390.0", "line_item": "depuldflrhkh24n, h100, gpu time cost" }, { "total": "50.43951744", "quantity": "193.998144", "unit_price": "26.0", "line_item": "zai-org/GLM-5.1, cached input tokens cost" } ] } ] } ``` ## Usage API `GET /v1/team/usage` returns usage buckets with metered quantities: request counts, token counts, and GPU time. You can filter and group by model, product type, and user. ### Parameters | Parameter | Type | Required | Description | | ----------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `start_time` | string (date-time) | Yes | RFC 3339 timestamp in UTC. Must fall on a 5-minute boundary. No earlier than one year ago. Alignment depends on `bucket_width`. | | `end_time` | string (date-time) | Yes | RFC 3339 timestamp in UTC on a 5-minute boundary. Its minute value must match `start_time`. | | `bucket_width` | string | No | `1d`, `1h`, or `5m`. Defaults to `1d`. | | `limit` | integer | No | Number of buckets. Defaults and maximums depend on `bucket_width`: `1d` → 7 / max 31, `1h` → 24 / max 168, `5m` → 12 / max 288. | | `page` | string | No | Pagination cursor from `next_page`. | | `group_by` | array of strings | No | Group usage by one or more of: `model`, `product_type`, `user_id`. | | `models` | array of strings | No | Filter to specific model IDs or endpoint IDs. | | `user_ids` | array of strings | No | Filter to specific users. | | `product_types` | array of strings | No | Filter to `model_apis` or `dedicated_endpoints`. | | `gpu_types` | array of strings | No | Filter to specific GPU types. Implies `product_types=dedicated_endpoints`. | | `X-Friendli-Team` | string (header) | No | Team ID to run the request as. | ### Example: Daily Usage Totals ```bash theme={null} curl --request GET \ --url "https://api.friendli.ai/v1/team/usage?start_time=2026-06-01T00:00:00Z&end_time=2026-06-08T00:00:00Z&bucket_width=1d" \ --header "Authorization: Bearer $FRIENDLIAI_API_KEY" ``` ```json expandable theme={null} { "has_more": false, "next_page": null, "data": [ { "start_time": "2026-06-01T00:00:00Z", "end_time": "2026-06-02T00:00:00Z", "results": [ { "num_model_requests": 4230, "input_tokens": 203290924, "input_cached_tokens": 193998144, "output_tokens": 1110820, "gpu_usage": { "h100": 330 }, "processed_audio_length_ms": 0 } ] } ] } ``` ### Example: Usage by Model and Product Type Group by `model` and `product_type` to see which models consumed the most tokens across both Model APIs and Dedicated Endpoints. ```bash theme={null} curl --request GET \ --url "https://api.friendli.ai/v1/team/usage?start_time=2026-06-01T00:00:00Z&end_time=2026-06-08T00:00:00Z&bucket_width=1d&group_by=model&group_by=product_type" \ --header "Authorization: Bearer $FRIENDLIAI_API_KEY" ``` ```json expandable theme={null} { "has_more": false, "next_page": null, "data": [ { "start_time": "2026-06-01T00:00:00Z", "end_time": "2026-06-02T00:00:00Z", "results": [ { "product_type": "dedicated_endpoints", "model": "depuldflrhkh24n", "num_model_requests": 0, "input_tokens": 0, "input_cached_tokens": 0, "output_tokens": 0, "gpu_usage": { "h100": 330 }, "processed_audio_length_ms": 0 }, { "product_type": "model_apis", "model": "zai-org/GLM-5.1", "num_model_requests": 2651, "input_tokens": 203257788, "input_cached_tokens": 193998144, "output_tokens": 938369, "processed_audio_length_ms": 0 } ] } ] } ``` ### Example: Usage by user Group by `user_id` to break down consumption per user. This shows who is driving usage across both Model APIs and Dedicated Endpoints. ```bash theme={null} curl --request GET \ --url "https://api.friendli.ai/v1/team/usage?start_time=2026-06-01T00:00:00Z&end_time=2026-06-08T00:00:00Z&bucket_width=1d&group_by=user_id&group_by=product_type" \ --header "Authorization: Bearer $FRIENDLIAI_API_KEY" ``` ```json expandable theme={null} { "has_more": false, "next_page": null, "data": [ { "start_time": "2026-06-01T00:00:00Z", "end_time": "2026-06-02T00:00:00Z", "results": [ { "product_type": "dedicated_endpoints", "user_id": "AvBI1gXTuRux", "num_model_requests": 1568, "input_tokens": 32928, "input_cached_tokens": 0, "output_tokens": 167805, "gpu_usage": { "h100": 330 }, "processed_audio_length_ms": 0 }, { "product_type": "model_apis", "user_id": "YmM5eyQ3J23q", "num_model_requests": 501, "input_tokens": 47473901, "input_cached_tokens": 45342336, "output_tokens": 314746, "processed_audio_length_ms": 0 } ] } ] } ``` #### Who is `user_id`? The `user_id` field identifies who consumed the usage, but the attribution depends on the product type: * **Model APIs**: The `user_id` is the owner of the Personal API Key that made the inference request. If multiple team members use the same API key, all usage is attributed to that key's owner. * **Dedicated Endpoints — token consumption**: The `user_id` is the owner of the Personal API Key that sent the request, same as Model APIs. * **Dedicated Endpoints — GPU time**: GPU time in the `gpu_usage` field is attributed to the user who **created the endpoint**, not the user who sent inference requests to it. If Alice creates an endpoint and Bob sends requests to it, the token usage appears under Bob's `user_id` but the GPU time appears under Alice's. When grouping by `user_id`, Dedicated Endpoints GPU time is attributed to the endpoint creator, not the API caller. If your chargeback model assumes per-request attribution, handle GPU time separately in your aggregation logic. Use `group_by=model` together with `group_by=user_id` to separate endpoint-level GPU time from token usage per user.