> ## 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 a user in a space

> Get credit usage for a user in a space.

The organization bot token must have the following scopes:

* `user:read`

Returns one person's Notion credit usage per billing period, starting with the current billing period and going back in time. The first result is the current billing period. Returns up to 100 periods per page by default; use `has_more` and `next_cursor` to get older periods.

`credits_used` is the person's usage in the period, in whole Notion credits, rounded down. It includes agents the person owns that run on their credits (`credit_source: "owner"`). That usage also appears in the agent's own credit usage.

The request returns a 404 `object_not_found` error when the user isn't a current member of the workspace or the workspace has no billing period.


## OpenAPI

````yaml openapi-adminApi.json GET /v1/spaces/{space_id}/users/{user_id}/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/{user_id}/credit_usage:
    get:
      tags:
        - Admin API
      summary: Get credit usage for a user in a space
      operationId: list-user-credit-usage-periods
      parameters:
        - $ref: '#/components/parameters/notionVersion'
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: User ID of the workspace member.
        - name: space_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: start_cursor
          in: query
          schema:
            type: string
            description: Opaque continuation cursor from the previous page.
        - name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            description: Number of billing periods 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_period
                    description: Always `user_credit_usage_period`
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        metrics_period_start_ms:
                          type: number
                          description: Start of the billing period (epoch ms, inclusive).
                        metrics_period_end_ms:
                          type: number
                          description: End of the billing period (epoch ms, exclusive).
                        credits_used:
                          type: number
                          minimum: 0
                          description: >-
                            Whole Notion credits used by this person in the
                            period, including agents they own that run on their
                            credits (credit_source "owner").
                      additionalProperties: false
                      required:
                        - metrics_period_start_ms
                        - metrics_period_end_ms
                        - credits_used
                      description: Credits used by a person in one monthly billing period.
                    maxItems: 100
                    description: >-
                      This person's usage per monthly billing period, newest
                      first.
                  has_more:
                    type: boolean
                    description: Whether older billing periods are available.
                  next_cursor:
                    oneOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      Cursor for the next page of billing periods, 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

````