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

# List credit usage

> Where credits were used, newest first: one entry per verification method of each candidate added to a campaign, and refunds or corrections as their own entries. Filter by campaign, candidate or time.

**Scope:** `credits:read`



## OpenAPI

````yaml /blue-collar-api/api-reference/openapi.json get /credits/usage
openapi: 3.1.0
info:
  title: Record Blue Collar API
  version: 1.0.0
  description: >-
    Run Record candidate verification from your own system. You need two things:
    your **key id** and your **secret**. Everything else is generated. See
    Authentication for how.
servers:
  - url: https://api-bc.userecord.io/api/v1/partner
    description: Blue Collar API
security: []
tags:
  - name: Skills
    description: The skill taxonomy, read live a page at a time
  - name: Skill requests
    description: Ask Record to add a missing skill
  - name: Lookups
    description: >-
      Lookups for filling in a job mandate: places in India, the countries an
      abroad job can be in, and the employment types and shifts the playground
      offers
  - name: Workflows
    description: >-
      Your organisation's blue-collar workflows (read all; change and
      soft-delete only the ones you created)
  - name: Job mandates
    description: >-
      Your organisation's job mandates, addressed by Record's mandate_id (read
      and change all of them)
  - name: Campaigns
    description: Contact candidates for one of your jobs and verify them. Spends credits
  - name: Results
    description: >-
      What Record collected from each candidate: status (pending, completed,
      declined, failed) and an output of answers and verdicts
  - name: Analytics
    description: >-
      The workflow Overview analytics of the Record playground: funnel,
      channels, follow-ups, calls, drop-offs, languages (read-only, scope
      analytics:read)
  - name: Credits
    description: >-
      The credits your organisation can spend and where they were used
      (read-only, scope credits:read)
paths:
  /credits/usage:
    get:
      tags:
        - Credits
      summary: List credit usage
      description: >-
        Where credits were used, newest first: one entry per verification method
        of each candidate added to a campaign, and refunds or corrections as
        their own entries. Filter by campaign, candidate or time.


        **Scope:** `credits:read`
      operationId: listCreditUsage
      parameters:
        - name: campaign_id
          in: query
          required: false
          description: Only the entries of this campaign
          schema:
            type: string
            pattern: ^[A-Za-z0-9_-]{4,64}$
          example: asmnt_9f2c41d7a8b3e65f
        - name: candidate_id
          in: query
          required: false
          description: Only the entries of this candidate
          schema:
            type: string
            pattern: ^[A-Za-z0-9_-]{4,64}$
        - name: from
          in: query
          required: false
          description: Only entries at or after this time
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: Only entries before this time
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          required: false
          description: 1 to 200, default 50
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          example: 50
        - name: cursor
          in: query
          required: false
          description: The next_cursor of the previous page
          schema:
            type: string
            maxLength: 512
      responses:
        '200':
          description: One page
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            ledger_id:
                              type: string
                            type:
                              type: string
                              description: >-
                                debit: credits used. refund, reversal or
                                adjustment: credits given back or corrected
                            service:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                skill_verification or data_enrichment; null for
                                an entry that is not tied to a method
                            service_label:
                              anyOf:
                                - type: string
                                - type: 'null'
                            quantity:
                              anyOf:
                                - type: number
                                - type: 'null'
                              description: Candidates this entry is for
                            unit_price:
                              anyOf:
                                - type: number
                                - type: 'null'
                            credits:
                              type: number
                              description: >-
                                Negative when credits were used, positive when
                                they were given back
                            balance_after:
                              type: number
                              description: The wallet's balance once this entry was applied
                            campaign_id:
                              anyOf:
                                - type: string
                                - type: 'null'
                            candidate_id:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: The candidate this entry is for
                            created_at:
                              type: string
                      count:
                        type: integer
                        description: How many items this page holds
                      total:
                        anyOf:
                          - type: integer
                          - type: 'null'
                        description: >-
                          How many items match your filters across all pages.
                          null when that cannot be counted cheaply: a filter
                          worked out per item (status, progress) on a list that
                          is large
                      next_cursor:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: >-
                          Pass as `cursor` for the next page; null on the last
                          page
                      has_more:
                        type: boolean
                        description: >-
                          true while there is a next page (with a status or
                          progress filter that page can still come back empty)
                      mode:
                        type: string
                        enum:
                          - live
                          - test
                        description: >-
                          The mode of your API key: a test key is about your
                          test credits, a live key about your live credits
                      totals:
                        type: object
                        properties:
                          credits_used:
                            type: number
                            description: >-
                              Credits used across all entries that match the
                              filters, net of anything given back
              example:
                success: true
                data:
                  items:
                    - ledger_id: LGR_5f2c1a9b7d3e4f60
                      type: debit
                      service: skill_verification
                      service_label: Scenario questions
                      quantity: 1
                      unit_price: 25
                      credits: -25
                      balance_after: 31750
                      campaign_id: asmnt_9f2c41d7a8b3e65f
                      candidate_id: cand_8f3a1c2e
                      created_at: '2026-10-05T12:41:11.000Z'
                  count: 1
                  total: 1
                  has_more: false
                  next_cursor: null
                  mode: live
                  totals:
                    credits_used: 25
        '400':
          description: >-
            `VALIDATION_FAILED`: Malformed `campaign_id`, `candidate_id`,
            `from`, `to` or `cursor`, or `from` is after `to`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKey: []
          SecretKey: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            pcall GET
            "/api/v1/partner/credits/usage?campaign_id=asmnt_9f2c41d7a8b3e65f&limit=50"
        - lang: javascript
          label: JavaScript
          source: >-
            const res = await call("GET",
            "/api/v1/partner/credits/usage?campaign_id=asmnt_9f2c41d7a8b3e65f&limit=50");

            const { data } = await res.json();
        - lang: python
          label: Python
          source: >-
            res = call("GET",
            "/api/v1/partner/credits/usage?campaign_id=asmnt_9f2c41d7a8b3e65f&limit=50")

            data = res.json()["data"]
components:
  schemas:
    Error:
      type: object
      properties:
        success:
          const: false
          type: boolean
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - VALIDATION_FAILED
                - LIMIT_EXCEEDED
                - UNAUTHORIZED
                - SCOPE_MISSING
                - FORBIDDEN
                - HTTPS_REQUIRED
                - NOT_FOUND
                - CONFLICT
                - INSUFFICIENT_CREDITS
                - IDEMPOTENCY_KEY_REQUIRED
                - IDEMPOTENCY_KEY_REUSED
                - IDEMPOTENCY_IN_PROGRESS
                - PAYLOAD_TOO_LARGE
                - UNSUPPORTED_MEDIA_TYPE
                - RATE_LIMITED
                - COOLDOWN
                - DAILY_CAP
                - SERVICE_DISABLED
                - SERVER_ERROR
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  message:
                    type: string
            request_id:
              type: string
              description: Quote it to Record support
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your key id, `VFN_TEST_…` or `VFN_LIVE_…`. Sent on every request.
    SecretKey:
      type: apiKey
      in: header
      name: x-secret-key
      description: >-
        Your secret, `VFN_SK_…`. **Not a real header, and never sent to the
        API.** It is only a form field for Try it, which uses it to sign your
        request in your browser. In your own code you sign each request with the
        secret and send `x-api-key`, `x-timestamp` and `x-signature` (see
        Authentication).

````

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