> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get activity

> Usage per UTC day and model over the last 30 completed days, oldest first. Today is not included until it ends. A day or model without usage has no row.



## OpenAPI

````yaml /openapi/management.yaml get /activity
openapi: 3.1.0
info:
  title: Pearl Management API
  version: '1.0'
  description: >-
    Read your organization's credits and usage with a management key, and let
    any API key describe itself. The Management API never runs inference: model
    requests go to the Inference API, with an inference key.
servers:
  - url: https://api.platform.pearlresearch.ai/api/v1
security:
  - managementKey: []
tags:
  - name: Credits
    description: The credits granted to your organization and how much of them is used.
  - name: API keys
    description: The limit, expiration, and spend of the key that calls.
  - name: Activity
    description: Daily usage per model.
paths:
  /activity:
    get:
      tags:
        - Activity
      summary: Get activity
      description: >-
        Usage per UTC day and model over the last 30 completed days, oldest
        first. Today is not included until it ends. A day or model without usage
        has no row.
      operationId: getActivity
      parameters:
        - name: date
          in: query
          required: false
          description: >-
            Return one day only: one of the last 30 completed UTC days,
            `YYYY-MM-DD`. Omit it for all 30.
          schema:
            type: string
            format: date
            example: '2026-11-14'
          example: '2026-11-14'
        - name: api_key_id
          in: query
          required: false
          description: >-
            Return one API key's usage only. The ID is the one in the key's API
            Keys page URL. An ID that matches none of your keys returns no rows.
            Omit it for all usage, Playground activity included.
          schema:
            type: string
            format: uuid
            example: 4c1f7a2e-8d3b-4e6a-9f10-2b7c5d8e1a34
      responses:
        '200':
          description: The activity rows.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: >-
                      One row per UTC day and model, ordered by date, then
                      model.
                    items:
                      $ref: '#/components/schemas/ActivityRow'
              example:
                data:
                  - date: '2026-11-13'
                    model: zai-org/GLM-5.3
                    usage: 0.8425
                    requests: 120
                    prompt_tokens: 1860000
                    completion_tokens: 84000
                    cached_tokens: 610000
                  - date: '2026-11-14'
                    model: deepseek-ai/DeepSeek-V4-Pro-0813
                    usage: 0.3102
                    requests: 42
                    prompt_tokens: 500000
                    completion_tokens: 51000
                    cached_tokens: 120000
                  - date: '2026-11-14'
                    model: zai-org/GLM-5.3
                    usage: 1.1053
                    requests: 156
                    prompt_tokens: 2400000
                    completion_tokens: 112000
                    cached_tokens: 790000
        '400':
          $ref: '#/components/responses/ActivityBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ManagementKeyRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/UsageSyncing'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            curl "https://api.platform.pearlresearch.ai/api/v1/activity" \
              -H "Authorization: Bearer $PEARL_MANAGEMENT_KEY"
        - lang: python
          label: Python
          source: |
            import os
            import requests

            response = requests.get(
                "https://api.platform.pearlresearch.ai/api/v1/activity",
                headers={"Authorization": f"Bearer {os.environ['PEARL_MANAGEMENT_KEY']}"},
            )
            response.raise_for_status()
            for row in response.json()["data"]:
                print(row["date"], row["model"], row["usage"])
        - lang: typescript
          label: TypeScript
          source: >
            const response = await
            fetch("https://api.platform.pearlresearch.ai/api/v1/activity", {
              headers: {Authorization: `Bearer ${process.env.PEARL_MANAGEMENT_KEY}`},
            });

            if (!response.ok) throw new Error((await
            response.json()).error.message);

            const {data} = await response.json();
components:
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per minute.
      schema:
        type: integer
      example: 10
    X-RateLimit-Remaining:
      description: Requests left in the current minute.
      schema:
        type: integer
      example: 9
    X-RateLimit-Reset:
      description: When the current minute's window ends, as a Unix timestamp in seconds.
      schema:
        type: integer
      example: 1763294460
    Retry-After:
      description: >-
        Seconds until the current window ends. Wait at least that long before
        retrying.
      schema:
        type: integer
      example: 37
  schemas:
    ActivityRow:
      type: object
      required:
        - date
        - model
        - usage
        - requests
        - prompt_tokens
        - completion_tokens
        - cached_tokens
      properties:
        date:
          type: string
          format: date
          description: The UTC day, midnight to midnight.
        model:
          type: string
          description: The model ID the usage was billed under.
        usage:
          type: number
          description: >-
            USD cost for the day and model, as billed. Usage that billing hasn't
            priced yet counts as 0 until it is.
        requests:
          type: integer
          description: Requests served.
        prompt_tokens:
          type: integer
          description: Input tokens, including the ones served from the prompt cache.
        completion_tokens:
          type: integer
          description: Output tokens.
        cached_tokens:
          type: integer
          description: >-
            Input tokens served from the prompt cache, billed at the cache-read
            rate. Already counted in `prompt_tokens`.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: integer
              description: The HTTP status code.
            message:
              type: string
              description: What went wrong.
  responses:
    ActivityBadRequest:
      description: >-
        A `date` that isn't one of the last 30 completed UTC days, an
        `api_key_id` that isn't a UUID, an unknown parameter, or a request
        covering more usage than one response can return. Retrying the same
        request fails again.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            dateOutOfRange:
              summary: Date outside the window
              value:
                error:
                  code: 400
                  message: >-
                    date must be one of the last 30 completed UTC days, in
                    YYYY-MM-DD format.
            invalidKeyId:
              summary: api_key_id not a UUID
              value:
                error:
                  code: 400
                  message: api_key_id must be an API key id (a UUID).
            unknownParameter:
              summary: Unknown parameter
              value:
                error:
                  code: 400
                  message: property foo should not exist
            tooMuchUsage:
              summary: Too much usage for one response
              value:
                error:
                  code: 400
                  message: >-
                    Too much usage to return in one response. Request one day at
                    a time with the date parameter.
    Unauthorized:
      description: >-
        A missing, unknown, revoked, or expired key. Retrying with the same key
        fails again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: No key
              value:
                error:
                  code: 401
                  message: 'Missing API key. Send it as Authorization: Bearer <key>.'
            invalid:
              summary: Unknown key
              value:
                error:
                  code: 401
                  message: Invalid API key.
            revoked:
              summary: Revoked key
              value:
                error:
                  code: 401
                  message: This API key has been revoked.
            expired:
              summary: Expired key
              value:
                error:
                  code: 401
                  message: This API key has expired.
    ManagementKeyRequired:
      description: An inference key, which can only call `GET /key`. Use a management key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 403
              message: >-
                This endpoint needs a management key (sk-prl-mgmt-...).
                Inference keys can only call GET /key.
    RateLimited:
      description: >-
        Rate limit exceeded: 10 requests per minute. Wait `Retry-After` seconds
        before retrying.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 429
              message: Rate limit exceeded. Please try again later.
    InternalError:
      description: Unexpected server error. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 500
              message: Internal server error.
    UsageSyncing:
      description: >-
        Usage for the window is not ready yet, for example while it syncs for
        the first time. Retry after a few seconds.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 503
              message: Usage history is syncing; retry shortly
  securitySchemes:
    managementKey:
      type: http
      scheme: bearer
      description: >-
        `Bearer` followed by a management key (`sk-prl-mgmt-`). Org admins
        create them on the [Management
        Keys](https://platform.pearlresearch.ai/management-keys) page. An
        inference key gets a `403`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.