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

# Get credits

> Retrieve the credits used and available for each metered feature of the workspace in the current period. Credits reset at the end of the period. Needs the contributor role or above in the workspace.



## OpenAPI

````yaml /schemas/2025-06-09.json get /v1/credits
openapi: 3.1.0
info:
  title: Folk External API
  description: >-
    Folk's public REST API lets you manage workspaces, groups, contacts, and
    real-time triggers.
  version: '2025-06-09'
  contact:
    name: folk
    email: tech@folk.app
    url: https://folk.app
servers:
  - url: https://api.folk.app
    description: Folk's public API production base URL.
    x-internal: false
security: []
tags:
  - name: Companies
    description: Operations related to companies.
  - name: Credits
    description: Operations related to credits.
  - name: Deals
    description: Operations related to deals.
  - name: Groups
    description: Operations related to groups.
  - name: Group members
    description: Operations related to group members.
  - name: Group custom fields
    description: Operations related to group custom fields.
  - name: Interactions
    description: Operations related to interactions.
  - name: Notes
    description: Operations related to notes.
  - name: People
    description: Operations related to people.
  - name: Person enrichments
    description: Operations related to person enrichments.
  - name: Reminders
    description: Operations related to reminders.
  - name: Tasks
    description: Operations related to tasks.
  - name: Users
    description: Operations related to users.
  - name: Webhooks
    description: Operations related to webhooks.
paths:
  /v1/credits:
    get:
      tags:
        - Credits
      summary: Get credits
      description: >-
        Retrieve the credits used and available for each metered feature of the
        workspace in the current period. Credits reset at the end of the period.
        Needs the contributor role or above in the workspace.
      operationId: getCredits
      responses:
        '200':
          description: The credits of the workspace.
          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'
            X-RateLimit-Limit-Burst:
              $ref: '#/components/headers/X-RateLimit-Limit-Burst'
            X-RateLimit-Remaining-Burst:
              $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
            X-RateLimit-Reset-Burst:
              $ref: '#/components/headers/X-RateLimit-Reset-Burst'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            feature:
                              type: string
                              enum:
                                - person_enrichment
                                - company_research
                                - ai_fields
                                - workflow_executions
                                - messages
                              description: >-
                                The metered feature. `person_enrichment`:
                                enrichment of people's emails and phones (`POST
                                /v1/person-enrichments`), charged per person and
                                field found. `company_research`: research on
                                companies. `ai_fields`: values generated by AI
                                in fields. `workflow_executions`: workflow
                                executions. `messages`: messages sent in
                                campaigns. New values may be added in the
                                future: handle unknown values gracefully.
                              example: person_enrichment
                            scope:
                              type: string
                              enum:
                                - workspace
                                - user
                              description: >-
                                Who shares the credits. `workspace`: one pool
                                shared by the whole workspace. `user`: each
                                member has their own pool; the values are those
                                of the user of the API key. New values may be
                                added in the future: handle unknown values
                                gracefully.
                              example: workspace
                            used:
                              type: integer
                              minimum: 0
                              description: >-
                                The credits consumed in the current period. Can
                                exceed `limit` if the limit was lowered during
                                the period.
                              example: 120
                            limit:
                              type:
                                - integer
                                - 'null'
                              minimum: 0
                              description: >-
                                The credits available per period, or null if
                                unlimited. 0 means the feature is not available.
                              example: 500
                            periodStart:
                              type: string
                              format: date-time
                              description: The start of the current period.
                              example: '2026-09-01T00:00:00.000Z'
                            periodEnd:
                              type: string
                              format: date-time
                              description: >-
                                The end of the current period, when `used`
                                resets to 0.
                              example: '2026-10-01T00:00:00.000Z'
                          required:
                            - feature
                            - scope
                            - used
                            - limit
                            - periodStart
                            - periodEnd
                        maxItems: 20
                        description: The credits of each metered feature, not paginated.
                    required:
                      - items
                    description: >-
                      The credits of the workspace for each metered feature, in
                      the current period.
                    example:
                      items:
                        - feature: person_enrichment
                          scope: workspace
                          used: 120
                          limit: 500
                          periodStart: '2026-09-01T00:00:00.000Z'
                          periodEnd: '2026-10-01T00:00:00.000Z'
                        - feature: company_research
                          scope: workspace
                          used: 12
                          limit: 200
                          periodStart: '2026-09-01T00:00:00.000Z'
                          periodEnd: '2026-10-01T00:00:00.000Z'
                        - feature: ai_fields
                          scope: workspace
                          used: 800
                          limit: 2000
                          periodStart: '2026-09-01T00:00:00.000Z'
                          periodEnd: '2026-10-01T00:00:00.000Z'
                        - feature: workflow_executions
                          scope: workspace
                          used: 3400
                          limit: null
                          periodStart: '2026-09-01T00:00:00.000Z'
                          periodEnd: '2026-10-01T00:00:00.000Z'
                        - feature: messages
                          scope: user
                          used: 40
                          limit: 2000
                          periodStart: '2026-09-01T00:00:00.000Z'
                          periodEnd: '2026-10-01T00:00:00.000Z'
                  deprecations:
                    type: array
                    items:
                      type: string
                    example:
                      - This field is deprecated
                required:
                  - data
              example:
                data:
                  items:
                    - feature: person_enrichment
                      scope: workspace
                      used: 120
                      limit: 500
                      periodStart: '2026-09-01T00:00:00.000Z'
                      periodEnd: '2026-10-01T00:00:00.000Z'
                    - feature: company_research
                      scope: workspace
                      used: 12
                      limit: 200
                      periodStart: '2026-09-01T00:00:00.000Z'
                      periodEnd: '2026-10-01T00:00:00.000Z'
                    - feature: ai_fields
                      scope: workspace
                      used: 800
                      limit: 2000
                      periodStart: '2026-09-01T00:00:00.000Z'
                      periodEnd: '2026-10-01T00:00:00.000Z'
                    - feature: workflow_executions
                      scope: workspace
                      used: 3400
                      limit: null
                      periodStart: '2026-09-01T00:00:00.000Z'
                      periodEnd: '2026-10-01T00:00:00.000Z'
                    - feature: messages
                      scope: user
                      used: 40
                      limit: 2000
                      periodStart: '2026-09-01T00:00:00.000Z'
                      periodEnd: '2026-10-01T00:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerApiKeyAuth: []
components:
  headers:
    X-RateLimit-Limit:
      schema:
        type: integer
        example: 1000
      description: >-
        The maximum number of requests that you can make in the current rate
        limit window.
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 998
      description: The number of requests remaining in the current rate limit window.
    X-RateLimit-Reset:
      schema:
        type: integer
        example: 1747322958
      description: >-
        The time at which the current rate limit window resets, in UTC epoch
        seconds.
    X-RateLimit-Limit-Burst:
      schema:
        type: integer
        example: 20
      description: >-
        The maximum number of requests that you can make in the current burst
        rate limit window.
    X-RateLimit-Remaining-Burst:
      schema:
        type: integer
        example: 18
      description: The number of requests remaining in the current burst rate limit window.
    X-RateLimit-Reset-Burst:
      schema:
        type: integer
        example: 1747322902
      description: >-
        The time at which the current burst rate limit window resets, in UTC
        epoch seconds.
    RateLimit-Policy:
      schema:
        type: string
        example: '"default";q=600;w=60, "burst";q=20;w=2'
      description: >-
        The rate limit policies applied to the request, as defined by the IETF
        RateLimit header fields draft. `q` is the number of requests allowed per
        window and `w` the window length in seconds.
    RateLimit:
      schema:
        type: string
        example: '"default";r=598;t=42, "burst";r=18;t=1'
      description: >-
        The current usage of each rate limit policy, as defined by the IETF
        RateLimit header fields draft. `r` is the number of requests remaining
        and `t` the number of seconds until the window resets.
    Retry-After:
      schema:
        type: integer
        example: 60
      description: >-
        The number of seconds to wait before making a new request after hitting
        the rate limit.
  responses:
    BadRequest:
      description: The request was unacceptable, often due to missing an invalid parameter.
      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'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_REQUEST
              message: The request was invalid.
              documentationUrl: https://developer.folk.app/api-reference/errors#bad-request
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Unauthorized:
      description: No valid API key provided.
      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'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: No valid API key provided.
              documentationUrl: https://developer.folk.app/api-reference/errors#unauthorized
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Forbidden:
      description: The API key doesn’t have permissions to perform the request.
      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'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FORBIDDEN
              message: The API key doesn’t have permissions to perform the request.
              documentationUrl: https://developer.folk.app/api-reference/errors#forbidden
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    NotFound:
      description: The requested resource doesn’t exist.
      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'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              documentationUrl: https://developer.folk.app/api-reference/errors#not-found
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    UnprocessableEntity:
      description: >-
        The request was unacceptable, often due to missing or invalid
        parameters.
      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'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNPROCESSABLE_ENTITY
              message: Invalid query parameters
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#unprocessable-entity
              details:
                issues:
                  - code: too_small
                    minimum: 1
                    type: number
                    inclusive: true
                    exact: false
                    message: Number must be greater than or equal to 1
                    path:
                      - limit
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    TooManyRequests:
      description: >-
        Too many requests hit the API too quickly. We recommend an exponential
        backoff of your requests.
      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'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error:
              code: TOO_MANY_REQUESTS
              message: You have exceeded your rate limit.
              documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
              details:
                policy: burst
                limit: 20
                remaining: 0
                windowSeconds: 2
                retryAfter: '2025-10-01T12:00:02.000Z'
                policies:
                  - policy: default
                    limit: 600
                    remaining: 412
                    windowSeconds: 60
                    retryAfter: '2025-10-01T12:01:00.000Z'
                  - policy: burst
                    limit: 20
                    remaining: 0
                    windowSeconds: 2
                    retryAfter: '2025-10-01T12:00:02.000Z'
    InternalServerError:
      description: Something went wrong on our end.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_SERVER_ERROR
              message: An internal server error occurred.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#internal-server-error
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    ServiceUnavailable:
      description: The server is overloaded or down for maintenance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SERVICE_UNAVAILABLE
              message: The service is currently unavailable.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#service-unavailable
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: TOO_MANY_REQUESTS
            message:
              type: string
              example: You have exceeded your rate limit.
            documentationUrl:
              type: string
              format: uri
              example: https://developer.folk.app/api-reference/errors#rate-limiting
            requestId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            timestamp:
              type: string
              format: date-time
              example: '2025-10-01T12:00:00Z'
            details:
              type: object
              additionalProperties: true
              example:
                policy: burst
                limit: 20
                remaining: 0
                windowSeconds: 2
                retryAfter: '2025-10-01T12:00:02.000Z'
          required:
            - code
            - message
            - documentationUrl
            - requestId
            - timestamp
      required:
        - error
      description: Error response containing error details.
    RateLimitError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: TOO_MANY_REQUESTS
            message:
              type: string
              example: You have exceeded your rate limit.
            documentationUrl:
              type: string
              format: uri
              example: https://developer.folk.app/api-reference/errors#rate-limiting
            requestId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            timestamp:
              type: string
              format: date-time
              example: '2025-10-01T12:00:00Z'
            details:
              type: object
              properties:
                policy:
                  type: string
                  enum:
                    - default
                    - burst
                  description: The name of the rate limit policy.
                limit:
                  type: integer
                  description: The maximum number of requests allowed per window.
                remaining:
                  type: integer
                  description: The number of requests remaining in the current window.
                windowSeconds:
                  type: integer
                  description: The length of the window, in seconds.
                retryAfter:
                  type: string
                  format: date-time
                  description: When the current window resets.
                policies:
                  type: array
                  items:
                    type: object
                    properties:
                      policy:
                        type: string
                        enum:
                          - default
                          - burst
                        description: The name of the rate limit policy.
                      limit:
                        type: integer
                        description: The maximum number of requests allowed per window.
                      remaining:
                        type: integer
                        description: >-
                          The number of requests remaining in the current
                          window.
                      windowSeconds:
                        type: integer
                        description: The length of the window, in seconds.
                      retryAfter:
                        type: string
                        format: date-time
                        description: When the current window resets.
                    required:
                      - policy
                      - limit
                      - remaining
                      - windowSeconds
                      - retryAfter
                  description: >-
                    The status of every rate limit policy applied to the
                    request.
              required:
                - policy
                - limit
                - remaining
                - windowSeconds
                - retryAfter
                - policies
              description: >-
                The exceeded rate limit policy. When several are exceeded, the
                one resetting last.
          required:
            - code
            - message
            - documentationUrl
            - requestId
            - timestamp
            - details
      required:
        - error
      description: Error response returned when a rate limit is exceeded.
  securitySchemes:
    bearerApiKeyAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````

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