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

> Get usage details for the team.

Get usage details for the team.

If `X-Friendli-Team` is omitted, this endpoint uses the default team configured in Friendli Suite.

To request successfully, it is mandatory to enter a **Personal API Key** (e.g. flp\_XXX) value in the **Bearer Token** field.
Refer to the [authentication section](/docs/openapi/introduction#authentication) on our introduction page to learn how to acquire this variable and [visit here](https://friendli.ai/suite/~/setting/keys) to generate your API Key.


## OpenAPI

````yaml https://github.com/friendliai/friendli-openapi/raw/refs/heads/main/openapi.yaml get /v1/team/usage
openapi: 3.1.0
info:
  title: Friendli Suite API Reference
  description: This is an OpenAPI reference of Friendli Suite API.
  termsOfService: https://friendli.ai/terms-of-service
  contact:
    name: FriendliAI Support Team
    email: support@friendli.ai
  version: 0.1.0
servers:
  - url: https://api.friendli.ai
security: []
tags:
  - name: Serverless.Chat
  - name: Serverless.ToolAssistedChat
  - name: Serverless.Responses
  - name: Serverless.Messages
  - name: Serverless.ChatRender
  - name: Serverless.Completions
  - name: Serverless.Token
  - name: Serverless.Audio
  - name: Serverless.Model
  - name: Serverless.Knowledge
  - name: Dedicated.Chat
  - name: Dedicated.Responses
  - name: Dedicated.Messages
  - name: Dedicated.ChatRender
  - name: Dedicated.Completions
  - name: Dedicated.Embeddings
  - name: Dedicated.TextClassification
  - name: Dedicated.Token
  - name: Dedicated.Image
  - name: Dedicated.Audio
  - name: Dedicated.Endpoint
  - name: Container.Chat
  - name: Container.Responses
  - name: Container.Messages
  - name: Container.Completions
  - name: Container.TextClassification
  - name: Container.Token
  - name: Container.Image
  - name: Container.Audio
  - name: Cost
  - name: Usage
  - name: Dataset
  - name: File
paths:
  /v1/team/usage:
    get:
      tags:
        - Usage
      summary: Get usage details for the team.
      operationId: getUsage
      parameters:
        - name: start_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: >-
              RFC 3339 timestamp in UTC. Must fall on a 5-minute boundary (e.g.,
              2026-01-01T10:05:00Z). It must be no earlier than one year ago.
              When `bucket_width=1h`, it must align to an hour boundary (e.g.,
              `10:00:00Z`); when `bucket_width=1d`, it must align to a day
              boundary (e.g., `00:00:00Z`).
            title: Start Time
          description: >-
            RFC 3339 timestamp in UTC. Must fall on a 5-minute boundary (e.g.,
            2026-01-01T10:05:00Z). It must be no earlier than one year ago. When
            `bucket_width=1h`, it must align to an hour boundary (e.g.,
            `10:00:00Z`); when `bucket_width=1d`, it must align to a day
            boundary (e.g., `00:00:00Z`).
        - name: end_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: >-
              RFC 3339 timestamp in UTC. Must fall on a 5-minute boundary (e.g.,
              2026-01-01T10:05:00Z), and its minute value must match
              `start_time`'s. It must obey the same hour/day alignment as
              `start_time` when `bucket_width=1h` or `1d`.
            title: End Time
          description: >-
            RFC 3339 timestamp in UTC. Must fall on a 5-minute boundary (e.g.,
            2026-01-01T10:05:00Z), and its minute value must match
            `start_time`'s. It must obey the same hour/day alignment as
            `start_time` when `bucket_width=1h` or `1d`.
        - name: bucket_width
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/UsageBucketWidth'
              - type: 'null'
            description: >-
              Width of each time bucket in response. Currently `1d`, `1h`, and
              `5m` are supported, default to `1d`.
            default: 1d
            title: Bucket Width
          description: >-
            Width of each time bucket in response. Currently `1d`, `1h`, and
            `5m` are supported, default to `1d`.
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: |-
              Specifies the number of buckets to return.
              - `bucket_width=1d`: default limit = 7, max limit = 31
              - `bucket_width=1h`: default limit = 24, max limit = 168
              - `bucket_width=5m`: default limit = 12, max limit = 288
            title: Limit
          description: |-
            Specifies the number of buckets to return.
            - `bucket_width=1d`: default limit = 7, max limit = 31
            - `bucket_width=1h`: default limit = 24, max limit = 168
            - `bucket_width=5m`: default limit = 12, max limit = 288
        - name: page
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              A cursor for use in pagination. Corresponding to the `next_page`
              field from the previous response.
            title: Page
          description: >-
            A cursor for use in pagination. Corresponding to the `next_page`
            field from the previous response.
        - name: group_by
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/UsageGroupBy'
              - type: 'null'
            description: >-
              Group the usage by the specified fields. Support fields include
              `model`, `product_type`, `user_id` and any combination of them.
            title: Group By
          description: >-
            Group the usage by the specified fields. Support fields include
            `model`, `product_type`, `user_id` and any combination of them.
        - name: models
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Return only usage for the listed Model APIs and Dedicated
              Endpoints. Values are model IDs, endpoint IDs, or a mix.
            title: Models
          description: >-
            Return only usage for the listed Model APIs and Dedicated Endpoints.
            Values are model IDs, endpoint IDs, or a mix.
        - name: user_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Return only usage for these users.
            title: User Ids
          description: Return only usage for these users.
        - name: product_types
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/ProductType'
              - type: 'null'
            description: >-
              Return only usage for the specified product types. Supported
              fields include `model_apis`, `dedicated_endpoints` and any
              combination of them.
            title: Product Types
          description: >-
            Return only usage for the specified product types. Supported fields
            include `model_apis`, `dedicated_endpoints` and any combination of
            them.
        - name: gpu_types
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Return only usage for the specified GPU types. When this filter is
              given, only 'gpu_usage' will be provided. Combining `gpu_types`
              with 'product_types=model_apis` is rejected with HTTP 400. 
            title: Gpu Types
          description: >-
            Return only usage for the specified GPU types. When this filter is
            given, only 'gpu_usage' will be provided. Combining `gpu_types` with
            'product_types=model_apis` is rejected with HTTP 400. 
        - name: X-Friendli-Team
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: ID of team to run requests as (optional parameter).
            title: X-Friendli-Team
          description: ID of team to run requests as (optional parameter).
      responses:
        '200':
          description: Team usage response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
              example:
                has_more: false
                data:
                  - start_time: '2023-11-07T00:00:00Z'
                    end_time: '2023-11-08T00:00:00Z'
                    results:
                      - num_model_requests: 1200
                        input_tokens: 180000
                        input_cached_tokens: 45000
                        output_tokens: 62000
                        product_type: model_apis
                        model: zai-org/GLM-5.2
                        user_id: user_id_123
                        processed_audio_length_ms: 0
                  - start_time: '2023-11-08T00:00:00Z'
                    end_time: '2023-11-09T00:00:00Z'
                    results:
                      - num_model_requests: 800
                        input_tokens: 120000
                        input_cached_tokens: 30000
                        output_tokens: 41000
                        product_type: dedicated_endpoints
                        model: dedicated-endpoint-01
                        user_id: user_id_456
                        gpu_usage:
                          a100: 120000
                          h100: 80000
                        processed_audio_length_ms: 0
        '400':
          description: Invalid request parameters
        '422':
          description: Unprocessable Entity
        '429':
          description: Rate limit exceeded
      security:
        - token: []
components:
  schemas:
    UsageBucketWidth:
      type: string
      enum:
        - 1d
        - 1h
        - 5m
      title: UsageBucketWidth
    UsageGroupBy:
      type: string
      enum:
        - model
        - product_type
        - user_id
      title: UsageGroupBy
    ProductType:
      type: string
      enum:
        - model_apis
        - dedicated_endpoints
      title: ProductType
    UsageResponse:
      properties:
        has_more:
          type: boolean
          title: Has More
        next_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page
        data:
          items:
            $ref: '#/components/schemas/UsageBucket'
          type: array
          title: Data
      type: object
      required:
        - has_more
        - data
      title: UsageResponse
    UsageBucket:
      properties:
        start_time:
          type: string
          format: date-time
          title: Start Time
        end_time:
          type: string
          format: date-time
          title: End Time
        results:
          items:
            $ref: '#/components/schemas/UsageResult'
          type: array
          title: Results
      type: object
      required:
        - start_time
        - end_time
        - results
      title: UsageBucket
    UsageResult:
      properties:
        product_type:
          anyOf:
            - $ref: '#/components/schemas/ProductType'
            - type: 'null'
          description: >-
            When `group_by=product_type`, this field provides the product type
            of the grouped usage result. Supported values are `model_apis` and
            `dedicated_endpoints`.
          examples:
            - model_apis
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: >-
            When `group_by=model`, this field provides the model ID of the
            grouped usage result. For Model APIs usage, this is the model ID.
            For Dedicated Endpoints usage, this is the endpoint ID.
          examples:
            - zai-org/GLM-5.2
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: >-
            When `group_by=user_id`, this field provides the user ID of the
            grouped usage result.
          examples:
            - user_id_123
        num_model_requests:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Model Requests
          description: The count of requests made.
          default: 0
          examples:
            - 1200
        input_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Input Tokens
          description: The aggregated number of input tokens used, including cached tokens.
          default: 0
          examples:
            - 180000
        input_cached_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Input Cached Tokens
          description: The aggregated number of input tokens that has been cached.
          default: 0
          examples:
            - 45000
        output_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Output Tokens
          description: The aggregated number of text output tokens used.
          default: 0
          examples:
            - 62000
        gpu_usage:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Gpu Usage
          description: >-
            The GPU time in seconds, keyed by GPU type. When `group_by=user_id`,
            this is attributed to the bucket of the user who created the
            endpoint. When the `gpu_types` filter is set, only Dedicated
            Endpoints usage is returned, and only GPU time is provided —
            per-GPU-type token usage is not yet supported.
          examples:
            - a100: 120000
              h100: 80000
        processed_audio_length_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Processed Audio Length Ms
          description: >-
            The number of processed audio length in milliseconds. Zero when
            there is no audio usage.
          default: 0
          examples:
            - 300000
      type: object
      title: UsageResult
  securitySchemes:
    token:
      type: http
      description: >-
        When using Friendli Suite API for inference requests, you need to
        provide a **Friendli Token** for authentication and authorization
        purposes.


        For more detailed information, please refer
        [here](https://friendli.ai/docs/openapi/introduction#authentication).
      scheme: bearer

````