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

# Get credit usage for users in a space

> Get credit usage for users in a space.

The organization bot token must have the following scopes:

* `user:read`

Lists every current member of the workspace, including members with no usage, ordered by user ID. Use `has_more` and `next_cursor` to page through members.

Each result reports Notion credits, the unit your workspace is billed in. `credits_used` is the person's usage in the current billing period, which `metrics_period_start_ms` and `metrics_period_end_ms` describe. `total_credits_used` is their usage across every billing period. Both include agents the person owns that run on their credits (`credit_source: "owner"`). That usage also appears in the agent's own credit usage. Credits are whole credits, rounded down.

`credit_limit` is the member credit limit that applies to the person right now, or `null` when no limit applies. It's `0` when the person has no limit and can't use Notion credits until one is set. It limits Notion credits only. The response doesn't say which setting the limit came from.

To see a person's usage in past billing periods, use [list credit usage per billing period for a user](https://developers.notion.com/reference/admin/list-user-credit-usage-periods.md).

The request returns a 404 `object_not_found` error when the workspace has no billing period.


## OpenAPI

````yaml openapi-adminApi.json GET /v1/spaces/{space_id}/users/credit_usage
openapi: 3.1.0
info:
  title: Notion Admin API
  version: 1.0.0
  termsOfService: >-
    https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac
servers:
  - url: https://api.notion.com/admin
security:
  - bearerAuth: []
tags:
  - name: Exports
    description: Workspace export endpoints
  - name: Legal holds
    description: Legal hold endpoints
  - name: Managed users
    description: Managed user endpoints
paths:
  /v1/spaces/{space_id}/users/credit_usage:
    get:
      tags:
        - Admin API
      summary: Get credit usage for users in a space
      operationId: list-user-credit-usage
      parameters:
        - $ref: '#/components/parameters/notionVersion'
        - name: space_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: start_cursor
          in: query
          schema:
            type: string
            minLength: 1
            description: Opaque continuation cursor from the previous page.
        - name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            description: Number of people per page (1–100; default 100).
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: list
                    description: Always `list`
                  type:
                    type: string
                    const: user_credit_usage
                    description: Always `user_credit_usage`
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        object:
                          type: string
                          const: user_credit_usage
                          description: Always `user_credit_usage`
                        id:
                          type: string
                          format: uuid
                          description: User ID of the workspace member.
                        credit_limit:
                          oneOf:
                            - type: integer
                              minimum: 0
                            - type: 'null'
                          description: >-
                            Effective credit limit on the member's Notion
                            credits for the current billing period, or null when
                            no limit applies. 0 when the member has no limit and
                            can't use Notion credits until one is set.
                        total_credits_used:
                          type: number
                          minimum: 0
                          description: >-
                            All-time whole Notion credits used by this person
                            across every billing period, including agents they
                            own that run on their credits (credit_source
                            "owner").
                        metrics_period_start_ms:
                          type: number
                          description: >-
                            Start of the current billing period (epoch ms,
                            inclusive).
                        metrics_period_end_ms:
                          type: number
                          description: >-
                            End of the current billing period (epoch ms,
                            exclusive).
                        credits_used:
                          type: number
                          minimum: 0
                          description: >-
                            Whole Notion credits used by this person in the
                            current billing period, including agents they own
                            that run on their credits (credit_source "owner").
                      additionalProperties: false
                      required:
                        - object
                        - id
                        - credit_limit
                        - total_credits_used
                        - metrics_period_start_ms
                        - metrics_period_end_ms
                        - credits_used
                    maxItems: 100
                    description: >-
                      Current workspace members on this page, including members
                      with no usage, ordered by user ID.
                  has_more:
                    type: boolean
                    description: Whether another page of people is available.
                  next_cursor:
                    oneOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      Opaque continuation cursor for the next page, or null when
                      has_more is false.
                additionalProperties: false
                required:
                  - object
                  - type
                  - results
                  - has_more
                  - next_cursor
        '400':
          description: The request body, path parameters, or query parameters are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adminApiPublicError400'
              example:
                object: error
                code: validation_error
                status: 400
                message: The request body is invalid.
        '401':
          description: The request is missing a valid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adminApiPublicError401'
              example:
                object: error
                code: unauthorized
                status: 401
                message: Unauthorized.
        '403':
          description: >-
            The authenticated bot does not have access to the requested resource
            or scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adminApiPublicError403'
              example:
                object: error
                code: restricted_resource
                status: 403
                message: Forbidden.
        '404':
          description: The requested resource could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adminApiPublicError404'
              example:
                object: error
                code: object_not_found
                status: 404
                message: Not found.
        '409':
          description: The request conflicts with the current state of the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adminApiPublicError409'
              example:
                object: error
                code: conflict_error
                status: 409
                message: The request conflicts with the current resource state.
        '429':
          description: The request was rate limited.
          headers:
            retry-after:
              description: Seconds to wait before retrying the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adminApiPublicError429'
              example:
                object: error
                code: rate_limited
                status: 429
                message: Rate limited.
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adminApiPublicError500'
              example:
                object: error
                code: internal_server_error
                status: 500
                message: An unexpected error occurred.
        '503':
          description: A required service is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adminApiPublicError503'
              example:
                object: error
                code: service_unavailable
                status: 503
                message: Service temporarily unavailable.
components:
  parameters:
    notionVersion:
      name: Notion-Version
      in: header
      required: true
      schema:
        enum:
          - '2026-06-01'
      description: The Admin API version to use for this request.
  schemas:
    adminApiPublicError400:
      type: object
      properties:
        object:
          enum:
            - error
        code:
          enum:
            - validation_error
        status:
          enum:
            - 400
        message:
          type: string
        additional_data:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      required:
        - object
        - code
        - status
        - message
      additionalProperties: false
    adminApiPublicError401:
      type: object
      properties:
        object:
          enum:
            - error
        code:
          enum:
            - unauthorized
        status:
          enum:
            - 401
        message:
          type: string
        additional_data:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      required:
        - object
        - code
        - status
        - message
      additionalProperties: false
    adminApiPublicError403:
      type: object
      properties:
        object:
          enum:
            - error
        code:
          enum:
            - restricted_resource
        status:
          enum:
            - 403
        message:
          type: string
        additional_data:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      required:
        - object
        - code
        - status
        - message
      additionalProperties: false
    adminApiPublicError404:
      type: object
      properties:
        object:
          enum:
            - error
        code:
          enum:
            - object_not_found
        status:
          enum:
            - 404
        message:
          type: string
        additional_data:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      required:
        - object
        - code
        - status
        - message
      additionalProperties: false
    adminApiPublicError409:
      type: object
      properties:
        object:
          enum:
            - error
        code:
          enum:
            - conflict_error
        status:
          enum:
            - 409
        message:
          type: string
        additional_data:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      required:
        - object
        - code
        - status
        - message
      additionalProperties: false
    adminApiPublicError429:
      type: object
      properties:
        object:
          enum:
            - error
        code:
          enum:
            - rate_limited
        status:
          enum:
            - 429
        message:
          type: string
        additional_data:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      required:
        - object
        - code
        - status
        - message
      additionalProperties: false
    adminApiPublicError500:
      type: object
      properties:
        object:
          enum:
            - error
        code:
          enum:
            - internal_server_error
        status:
          enum:
            - 500
        message:
          type: string
        additional_data:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      required:
        - object
        - code
        - status
        - message
      additionalProperties: false
    adminApiPublicError503:
      type: object
      properties:
        object:
          enum:
            - error
        code:
          enum:
            - service_unavailable
        status:
          enum:
            - 503
        message:
          type: string
        additional_data:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      required:
        - object
        - code
        - status
        - message
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````