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

# Get Billable Users

> Retrieve the list of billable users for a specific Petra tenant. A user is considered billable if they have non-empty assignedLicenseSkuIds and are not deleted (deletedAt is null).

<Note>For common API errors, see [API Troubleshooting](/api-reference/troubleshooting).</Note>

<Note>This route is limited to **1 request per minute**.</Note>


## OpenAPI

````yaml GET /v1/billable-users
openapi: 3.0.3
info:
  title: Petra Security API
  description: >-
    The Petra Security API provides programmatic access to security data and
    functionality within your Petra portal.
  version: 1.0.0
  contact:
    name: Petra Security Support
    email: support@petrasecurity.com
servers:
  - url: https://api.petrasecurity.com
    description: Production server
security:
  - bearerAuth: []
paths:
  /v1/billable-users:
    get:
      tags: []
      summary: Get billable users
      description: >-
        Retrieve the list of billable users for a specific Petra tenant. A user
        is considered billable if they have non-empty assignedLicenseSkuIds and
        are not deleted (deletedAt is null).
      operationId: getBillableUsers
      parameters:
        - name: tenantId
          in: query
          required: true
          description: >-
            The Petra tenant ID to get billable users for. The endpoint verifies
            that the requested tenant belongs to the organization associated
            with the API key.
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillableUsersResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Tenant does not belong to your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded for this route
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    BillableUsersResponse:
      type: object
      properties:
        tenantId:
          type: string
          description: The Petra tenant ID
        tenantDisplayName:
          type: string
          description: The display name of the tenant
        microsoftTenantId:
          type: string
          description: The Microsoft tenant ID associated with this Petra tenant
        reportGeneratedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp indicating when this report was generated
        totalBillableUsers:
          type: integer
          description: The total count of billable users in the tenant
        projectedBillableUnitsThisMonth:
          type: integer
          description: >-
            The prorated number of billable units for this tenant in the current
            month. This value accounts for mid-month onboarding and is the
            number used for billing.
        users:
          type: array
          description: Array of billable user objects
          items:
            $ref: '#/components/schemas/BillableUser'
      example:
        tenantId: petra-tenant-123
        tenantDisplayName: Acme Corporation
        microsoftTenantId: abcd1234-5678-90ef-ghij-klmnopqrstuv
        reportGeneratedAt: '2026-01-06T12:00:00.000Z'
        totalBillableUsers: 42
        projectedBillableUnitsThisMonth: 28
        users:
          - id: user-id-1
            displayName: John Doe
            userPrincipalName: john.doe@example.com
            mail: john.doe@example.com
            accountEnabled: true
            assignedLicenseSkuIds:
              - sku-id-1
              - sku-id-2
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: string
              description: Additional error details
      example:
        error:
          code: UNAUTHORIZED
          message: Invalid API key
          details: The provided API key is invalid or has been revoked
    BillableUser:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the user
        displayName:
          type: string
          description: The display name of the user
        userPrincipalName:
          type: string
          description: The user principal name (typically the user's email/login)
        mail:
          type: string
          description: The user's email address
        accountEnabled:
          type: boolean
          description: Whether the user account is currently enabled
        assignedLicenseSkuIds:
          type: array
          description: Array of SKU IDs for licenses assigned to this user
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication. Include your API key in the Authorization
        header as 'Bearer YOUR_API_KEY'

````