> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-ad5578da.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

export const TableOfContents = ({title = 'On this page', items, minHeadingLevel = 2, maxHeadingLevel = 3, className = '', activeClassName = 'text-primary dark:text-primary-light border-primary dark:border-primary-light hover:border-primary dark:hover:border-primary-light', inactiveClassName = 'hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-300'}) => {
  const [toc, setToc] = useState(items ?? []);
  const [activeId, setActiveId] = useState('');
  useEffect(() => {
    if (items && items.length) return;
    if (typeof document === 'undefined') return;
    const selectors = [];
    for (let lvl = minHeadingLevel; lvl <= maxHeadingLevel; lvl++) {
      selectors.push(`h${lvl}`);
    }
    const nodes = Array.from(document.querySelectorAll(selectors.join(','))).filter(el => el.id);
    const built = [];
    let currentTop = null;
    nodes.forEach(el => {
      const level = Number(el.tagName.slice(1));
      const node = {
        id: el.id,
        label: el.textContent.trim(),
        href: `#${el.id}`,
        children: []
      };
      if (level === minHeadingLevel) {
        built.push(node);
        currentTop = node;
      } else if (level > minHeadingLevel && currentTop) {
        currentTop.children.push(node);
      } else {
        built.push(node);
      }
    });
    setToc(built);
  }, [items, minHeadingLevel, maxHeadingLevel]);
  useEffect(() => {
    if (typeof document === 'undefined') return;
    const applyHash = () => {
      const h = window.location.hash.replace('#', '');
      if (h) setActiveId(h);
    };
    applyHash();
    const observer = new IntersectionObserver(entries => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          setActiveId(entry.target.id);
        }
      });
    }, {
      rootMargin: '0px 0px -70% 0px',
      threshold: 0.1
    });
    const ids = toc.flatMap(i => [i, ...i.children ?? []]).map(i => i.id);
    ids.forEach(id => {
      const el = document.getElementById(id);
      if (el) observer.observe(el);
    });
    window.addEventListener('hashchange', applyHash);
    return () => {
      window.removeEventListener('hashchange', applyHash);
      observer.disconnect();
    };
  }, [toc]);
  const Item = ({node, depth = 0}) => {
    const isActive = activeId === node.id;
    return <li className="toc-item relative ml-6" data-depth={depth}>
        <a href={node.href} className={`py-1 block font-medium ${isActive ? activeClassName : inactiveClassName}`} style={depth > 0 ? {
      marginLeft: `${depth}rem`
    } : {}} onClick={() => setActiveId(node.id)}>
          {node.label}
        </a>
        {node.children && node.children.length > 0 && <>
            {node.children.map(child => <Item node={child} depth={depth + 1} key={child.href} />)}
          </>}
      </li>;
  };
  const data = toc && toc.length ? toc : items || [];
  return <div className={`text-gray-600 text-sm leading-6 w-[18rem] pb-4 -mt-10 pt-10 hidden xl:block ${className}`} id="table-of-contents-custom">
      <ul id="table-of-contents-custom-content" className="toc">
        <li className="toc-item relative">
          <div className="text-gray-700 dark:text-gray-300 font-medium flex items-center space-x-2 py-1">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="2" xmlns="http://www.w3.org/2000/svg" className="h-3 w-3">
              <path d="M2.44434 12.6665H13.5554" strokeLinecap="round" strokeLinejoin="round"></path>
              <path d="M2.44434 3.3335H13.5554" strokeLinecap="round" strokeLinejoin="round"></path>
              <path d="M2.44434 8H7.33323" strokeLinecap="round" strokeLinejoin="round"></path>
            </svg>
            <span>{title}</span>
          </div>
        </li>
        {data.map(node => <Item node={node} key={node.href} />)}
      </ul>
    </div>;
};

<Panel>
  <TableOfContents />
</Panel>

<Tip> 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.</Tip>

### Examples

<Tabs>
  <Tab title="API Request">
    ```bash wrap theme={null}
      curl -X 'GET' \
     'https://api.usecortex.ai/tenants/stats?tenant_id=tenant_123' \
      --header 'Authorization: Bearer YOUR_API_KEY'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const stats = await client.tenant.stats({
      tenant_id: "tenant_1234",
      sub_tenant_id: "sub_tenant_4567"
    });
    ```
  </Tab>

  <Tab title="Python (Sync)">
    ```python theme={null}
    # Async usage is similar, just use async_client and await
    stats = client.tenant.stats(
        tenant_id="tenant_1234",
        sub_tenant_id="sub_tenant_4567"
    )
    ```
  </Tab>
</Tabs>

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](/api-reference/error-responses) documentation.


## OpenAPI

````yaml GET /tenants/stats
openapi: 3.1.0
info:
  title: Cortex SDK API
  description: REST APIs for Cortex AI retrieval engine
  version: 0.0.1
servers:
  - url: /
    description: Local
    x-fern-server-name: cortex-backend-local
  - url: https://api.usecortex.ai
    description: Production
    x-fern-server-name: cortex-prod
    x-fern-audiences:
      - public
  - url: https://preprod.usecortex.ai
    description: Staging
    x-fern-server-name: cortex-staging
security: []
paths:
  /tenants/stats:
    get:
      tags:
        - tenants
      summary: Get Tenant Stats
      description: >-
        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.
      operationId: get_tenant_stats_tenants_stats_get
      parameters:
        - name: tenant_id
          in: query
          required: true
          schema:
            type: string
            title: Tenant Id
            description: Unique identifier for the tenant/organization
            example: tenant_1234
          description: Unique identifier for the tenant/organization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantStatsResponse'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '403':
          description: Forbidden - Access denied
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '422':
          description: Unprocessable Entity - Validation failed
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
      security:
        - HTTPBearer: []
components:
  schemas:
    TenantStatsResponse:
      properties:
        tenant_id:
          type: string
          title: Tenant Id
          description: Tenant identifier
          example: tenant_1234
        normal_collection:
          $ref: '#/components/schemas/CollectionStats'
          description: Statistics for the normal (context) collection
        memory_collection:
          $ref: '#/components/schemas/CollectionStats'
          description: Statistics for the memory collection
        message:
          type: string
          title: Message
          description: Summary message
          default: Successfully retrieved tenant collection statistics
      type: object
      required:
        - tenant_id
        - normal_collection
        - memory_collection
      title: TenantStatsResponse
    cortex__models__response__commons__ActualErrorResponse:
      properties:
        detail:
          $ref: >-
            #/components/schemas/cortex__models__response__commons__ErrorResponse
      type: object
      required:
        - detail
      title: ActualErrorResponse
    CollectionStats:
      properties:
        row_count:
          type: integer
          title: Row Count
          description: Number of rows in the collection
          example: 1
        dimensions:
          type: integer
          title: Dimensions
          description: Number of dimensions in the collection
          example: 1
      type: object
      required:
        - row_count
        - dimensions
      title: CollectionStats
    cortex__models__response__commons__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          default: false
          example: true
        message:
          type: string
          title: Message
          default: Error occurred
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
      type: object
      title: ErrorResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````