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

# Get token usage history

> Return a paginated ledger of every token movement for your workspace — charges, refunds, grants, and expirations — ordered newest first. Use the `before` cursor with the `created_at` of the last entry you saw to page backward.



## OpenAPI

````yaml /api-reference/openapi.json get /credits/history
openapi: 3.1.0
info:
  title: Fribl API
  description: >-
    The Fribl API enables intelligent talent matching powered by AI. Analyze CVs
    and job descriptions from text or file uploads, search and manage skills,
    match candidates to positions with configurable scoring weights, and source
    candidate profiles from external databases. All document processing is
    asynchronous — submit documents for analysis, poll for status, and retrieve
    structured results when ready.
  version: 1.0.0
  contact:
    name: Fribl Support
    url: https://fribl.co
servers:
  - url: https://api-service.fribl.co/api/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: CVs
    description: >-
      Upload, analyze, retrieve, update, and delete candidate CVs. CVs can be
      submitted as raw text or as PDF file uploads. Processing is asynchronous —
      use the status endpoint to track progress.
  - name: Jobs
    description: >-
      Upload, analyze, retrieve, update, and delete job descriptions. Jobs can
      be submitted as raw text or as PDF file uploads. Processing is
      asynchronous — use the status endpoint to track progress.
  - name: Matching
    description: >-
      Match analyzed CVs against job descriptions using AI-powered scoring.
      Configure weights across experience, hard skills, soft skills, and
      education dimensions to tailor match results to your hiring priorities.
  - name: Sourcing
    description: >-
      Search for candidate profiles from external sources, retrieve cached
      search results, and ingest selected profiles into your Fribl workspace for
      matching.
  - name: Skills
    description: >-
      Search the Fribl skills taxonomy and retrieve available languages for
      skill translation. These endpoints are publicly accessible and do not
      require authentication.
  - name: Tokens
    description: >-
      Inspect your workspace's usage-based token balance, review the ledger of
      every charge and refund, and read the live per-action price list. Billable
      endpoints deduct tokens and return 402 when the balance is insufficient.
      Tokens are purchased and managed in the Fribl Console
      (https://console.fribl.co).
paths:
  /credits/history:
    get:
      tags:
        - Tokens
      summary: Get token usage history
      description: >-
        Return a paginated ledger of every token movement for your workspace —
        charges, refunds, grants, and expirations — ordered newest first. Use
        the `before` cursor with the `created_at` of the last entry you saw to
        page backward.
      operationId: getTokenHistory
      parameters:
        - name: limit
          in: query
          description: Maximum number of ledger entries to return.
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 500
        - name: before
          in: query
          description: >-
            Return only entries created strictly before this ISO 8601 timestamp.
            Use for backward pagination.
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Ledger entries, newest first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TokenLedgerEntry'
                required:
                  - data
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    TokenLedgerEntry:
      type: object
      description: >-
        A single immutable token movement. Charges are negative; refunds and
        grants are positive.
      properties:
        id:
          type: string
          description: Ledger entry identifier.
          example: '10472'
        workspace_id:
          type: string
          example: ws_a1b2c3d4
        action:
          type: string
          description: >-
            Billable action (e.g. `cv_processing`) or a balance event such as
            `grant` or `token_expired`. A positive amount on a billable action
            is a refund of a prior charge.
          example: cv_processing
        amount:
          type: integer
          description: >-
            Signed token change. Negative for a charge, positive for a refund or
            grant.
          example: -1
        balance_after:
          type: string
          description: Balance immediately after this entry was applied.
          example: '151'
        reference_id:
          type: string
          nullable: true
          description: Task, match, or session this entry is tied to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        metadata:
          type: object
          nullable: true
          description: Optional structured context, such as a refund reason.
        created_at:
          type: string
          format: date-time
          example: '2026-06-03T10:15:30.000Z'
      required:
        - id
        - workspace_id
        - action
        - amount
        - balance_after
        - created_at
    ErrorResponse:
      type: object
      description: Standard error response.
      properties:
        error:
          type: string
          description: Human-readable error message.
      required:
        - error
  responses:
    Unauthorized:
      description: >-
        Authentication failed. Provide a valid API key in the `x-api-key`
        header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key in UUID format. Include this header with every authenticated
        request.

````