Skip to main content
GET
/
tenant
/
sub_tenant_ids
Get Sub Tenant Ids
curl --request GET \
  --url https://api.usecortex.ai/tenant/sub_tenant_ids \
  --header 'Authorization: Bearer <token>'
{
  "tenant_id": "tenant_1234",
  "sub_tenant_ids": [
    "sub_tenant_1234",
    "sub_tenant_4567"
  ],
  "count": 1,
  "tenant_schema": {
    "properties": [
      {
        "field_name": "field_1",
        "index_filterable": true,
        "index_searchable": true
      },
      {
        "field_name": "field_2",
        "index_filterable": false,
        "index_searchable": true
      }
    ]
  },
  "success": true,
  "message": "Sub-tenant IDs fetched successfully"
}
Hit the Try it button to try this API now in our playground. It’s the best way to check the full request and response in one place, customize your parameters, and generate ready-to-use code snippets.

​
Sample Request

curl --request GET \
  --url 'https://api.usecortex.ai/tenant/sub_tenant_ids?tenant_id=tenant_1234' \
  --header 'Authorization: Bearer YOUR_API_KEY'
Retrieve all sub-tenant IDs contained within a specific tenant directly from the underlying data store for a comprehensive list of all subdivisions.

​
Use Cases

​
Tenant Administration

  • Audit Sub-Tenants: Get a complete list of all sub-tenants in your organization
  • Monitor Usage: Track how many sub-tenants are actively being used
  • Data Management: Understand the scope of your multi-tenant setup

​
Application Development

  • Dynamic UI: Build interfaces that adapt based on available sub-tenants
  • Access Control: Implement role-based access by checking available sub-tenants
  • Analytics: Generate reports on sub-tenant usage and distribution

​
Integration Scenarios

  • Bulk Operations: Perform operations across multiple sub-tenants
  • Migration: Plan data migration or consolidation across sub-tenants
  • Compliance: Generate compliance reports showing data distribution

​
Query Parameters

  • tenant_id (required): The primary tenant ID to fetch sub-tenant IDs for

​
Response Format

The endpoint returns a structured response containing:
  • tenant_id: The tenant ID that was queried
  • sub_tenant_ids: Array of all sub-tenant IDs within the tenant
  • count: Total number of sub-tenants found
  • message: Success message with additional context

​
Example Request

GET /tenant/sub_tenant_ids?tenant_id=acme_corp

​
Example Response

{
  "tenant_id": "acme_corp",
  "sub_tenant_ids": [
    "default",
    "engineering",
    "sales",
    "marketing",
    "hr",
    "user_12345",
    "user_67890",
    "project_alpha"
  ],
  "count": 8,
  "message": "Successfully retrieved sub-tenant IDs for tenant acme_corp"
}

​
Response Details

​
Sub-Tenant ID Types

The response may include different types of sub-tenant IDs: Default Sub-Tenant:
  • "default" - The automatically created default sub-tenant
Department-Based Sub-Tenants:
  • "engineering", "sales", "marketing" - Organizational departments
User-Based Sub-Tenants:
  • "user_12345", "user_67890" - Individual user workspaces (B2C applications)
Project-Based Sub-Tenants:
  • "project_alpha", "client_beta" - Project or client-specific workspaces

​
Understanding the Count

The count field represents the total number of sub-tenants, including:
  • The default sub-tenant (always present)
  • All custom sub-tenants created through uploads
  • Any sub-tenants created through other API operations
Default Sub-Tenant: Every tenant automatically has a “default” sub-tenant that serves as the organization-wide workspace. This will always be included in the sub-tenant IDs list.

​
Error Handling

​
Common Error Scenarios

Invalid Tenant ID: 
{
  "error": "Tenant not found",
  "message": "The specified tenant_id does not exist or you don't have access to it"
}
Authentication Issues: 
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
Internal Server Error: 
{
  "error": "Internal server error",
  "message": "Failed to fetch sub-tenant IDs"
}
Performance: This API provides real-time data directly from the underlying data store, ensuring you always get the most current list of sub-tenants.
Rate Limiting: While this API is efficient, avoid calling it excessively in production applications. Consider caching the results for a reasonable period if you need frequent access to this data.

​
Error Responses

All endpoints return consistent error responses following the standard format. For detailed error information, see our Error Responses documentation.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
tenant_id
string
required
Example:

"tenant_1234"

Response

Successful Response

​
tenant_id
string
required

The tenant ID that was queried

Example:

"tenant_1234"

​
sub_tenant_ids
string[]
required

Array of all sub-tenant IDs within the tenant

Example:
["sub_tenant_1234", "sub_tenant_4567"]
​
count
integer
required

Total number of sub-tenants found

Required range: x >= 0
Example:

1

​
tenant_schema
object | null

Schema configuration for the tenant collection

Example:
{
  "properties": [
    {
      "field_name": "field_1",
      "index_filterable": true,
      "index_searchable": true
    },
    {
      "field_name": "field_2",
      "index_filterable": false,
      "index_searchable": true
    }
  ]
}
​
success
boolean
default:true

Indicates whether the sub-tenant retrieval was successful

Example:

true

​
message
string
default:Sub-tenant IDs fetched successfully

Response message describing the operation result

⌘I