Get Tenant Stats

Retrieve usage stats for your tenant.

Use this endpoint to check whether a tenant exists and view core metrics like total indexed objects and vector dimension. This helps you validate setup and monitor ingestion.

Expected outcome

You receive the current object count and vector dimension for the tenant. If the tenant does not exist, you get a not-found error.

GET /tenants/stats

Error

A valid request URL is required to generate request examples

200

{
  "tenant_id": "tenant_1234",
  "normal_collection": {
    "row_count": 1,
    "dimensions": 1
  },
  "memory_collection": {
    "row_count": 1,
    "dimensions": 1
  },
  "message": "Successfully retrieved tenant collection statistics"
}

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.

Examples

API Request

  curl -X 'GET' \
 'https://api.usecortex.ai/tenants/stats?tenant_id=tenant_123' \
  --header 'Authorization: Bearer YOUR_API_KEY'

TypeScript

const stats = await client.tenant.stats({
  tenant_id: "tenant_1234",
  sub_tenant_id: "sub_tenant_4567"
});

Python (Sync)

# Async usage is similar, just use async_client and await
stats = client.tenant.stats(
    tenant_id="tenant_1234",
    sub_tenant_id="sub_tenant_4567"
)

Retrieve statistics for a specific tenant or sub-tenant to get insights into organizational data including object count, vector dimensions, and tenant information.

Query Parameters

• tenant_id: Required string - Primary organizational identifier (e.g., enterprise client, company) for multi-tenant data isolation
• sub_tenant_id: Optional string - Secondary organizational identifier (e.g., department, team, project) within a tenant for hierarchical data organization; defaults to tenant_id if not provided

Multi-Tenant Context

This API leverages Cortex’s hierarchical tenant system where:

• Tenant Level: Stats for an entire organization (e.g., “acme_corp”)
• Sub-Tenant Level: Stats for specific departments or teams within an organization (e.g., “engineering” within “acme_corp”)
• Data Isolation: All statistics are completely isolated per tenant/sub-tenant combination

Response Details

• object_count: Number of objects/embeddings stored for the tenant
• vector_dimension: Dimension size of the embedding vectors for this tenant
• tenant_id: The name/identifier of the tenant

Use Cases

This API is useful for:

• Monitoring: Track the number of embeddings stored for a tenant or department
• Validation: Verify vector dimensions before uploading new embeddings to ensure compatibility
• Analytics: Generate usage reports and statistics for billing, compliance, or optimization
• Capacity Planning: Understand storage requirements and usage patterns across organizations
• Multi-Tenant Management: Monitor data distribution across enterprise clients and their departments
• Department Insights: Compare usage patterns between different teams within the same organization

Example Scenarios

• Enterprise Dashboard: tenant_id="acme_corp" to see total company usage
• Department Analytics: tenant_id="acme_corp", sub_tenant_id="engineering" for team-specific stats
• Client Reporting: Generate individual reports for each enterprise client in your B2B platform

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

Unique identifier for the tenant/organization

Example:

"tenant_1234"

Response

200

application/json

Successful Response

tenant_id · string · required

Tenant identifier

Example:

"tenant_1234"

normal_collection · CollectionStats · object · required

Statistics for the normal (context) collection

Show child attributes

memory_collection · CollectionStats · object · required

Statistics for the memory collection

Show child attributes

message · string · default: Successfully retrieved tenant collection statistics

Summary message