> ## 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 Tenants

> List the Petra tenants in your organization. Use this to discover Petra tenant IDs to pass to the other endpoints. Removed (deleted) tenants are excluded; paused tenants are included with `isPaused: true`.

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

<Note>This route is limited to **10 requests per minute**.</Note>


## OpenAPI

````yaml GET /v1/tenants
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/tenants:
    get:
      tags: []
      summary: Get tenants
      description: >-
        List the Petra tenants in your organization. Use this to discover Petra
        tenant IDs to pass to the other endpoints. Removed (deleted) tenants are
        excluded; paused tenants are included with `isPaused: true`.
      operationId: getTenants
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTenantsResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          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:
    GetTenantsResponse:
      type: object
      properties:
        totalTenants:
          type: integer
          description: The number of tenants returned
        tenants:
          type: array
          description: Tenants in your organization, sorted alphabetically by name
          items:
            $ref: '#/components/schemas/TenantsResponseItem'
      example:
        totalTenants: 2
        tenants:
          - petraTenantId: ZZk90t
            name: Acme Corporation
            microsoftTenantId: abcd1234-5678-90ef-ghij-klmnopqrstuv
            isPaused: false
            onboardingDate: '2025-01-15T00:00:00.000Z'
          - petraTenantId: Y3mPqr
            name: Globex Inc.
            microsoftTenantId: ffff0000-1111-2222-3333-444455556666
            isPaused: true
            onboardingDate: '2024-09-02T00:00:00.000Z'
    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
    TenantsResponseItem:
      type: object
      properties:
        petraTenantId:
          type: string
          description: >-
            The Petra tenant ID (found in the dashboard URL:
            app.petrasecurity.com/tenant/<petraTenantId>)
        name:
          type: string
          description: Display name of the tenant
        microsoftTenantId:
          type: string
          description: The Microsoft tenant ID
        isPaused:
          type: boolean
          description: >-
            Whether ingestion for this tenant is currently paused. Paused
            tenants are still listed.
        onboardingDate:
          type: string
          format: date-time
          description: When this tenant was onboarded to Petra (ISO 8601)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication. Include your API key in the Authorization
        header as 'Bearer YOUR_API_KEY'

````