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

# Read table shapes

> Returns the most recent snapshot of the columns of each table in this Workspace's catalog, with their distributions, a page at a time. tenantConnectorTapId keeps only the tables of that Tap. A page holds at most limit snapshots: 20 by default, 100 at most. It stops before 40,000 characters of snapshots, but it always holds one. To read the next page, send nextOffset as offset. The last page has no nextOffset.

## Access

An MCP token or a Parable token can call this operation. See [Authentication](https://developers.askparable.com/getting-started/authentication.md) for the kinds of token.

Your roles must grant `tenant.data.catalog`.

## Errors

* `WA-TN-001`: No Workspace context was supplied. Call from a Workspace context.
* `HTTP 400`: limit is not from 1 to 100, or offset is less than 0. Send a limit from 1 to 100 and an offset of 0 or more, such as the nextOffset of the page before.


## OpenAPI

````yaml /api-reference/openapi.json get /api/catalog/table-shape-stats
openapi: 3.0.3
info:
  description: >-
    Use the Workspace API to work with artifacts, connectors, Parables, and
    account resources.
  title: Workspace API
  version: v2026.11.20.3
servers: []
security: []
paths:
  /api/catalog/table-shape-stats:
    get:
      tags:
        - Catalog
      summary: Read table shapes
      description: >-
        Returns the most recent snapshot of the columns of each table in this
        Workspace's catalog, with their distributions, a page at a time.
        tenantConnectorTapId keeps only the tables of that Tap. A page holds at
        most limit snapshots: 20 by default, 100 at most. It stops before 40,000
        characters of snapshots, but it always holds one. To read the next page,
        send nextOffset as offset. The last page has no nextOffset.
      operationId: CatalogTableShapeStatsHandler
      parameters:
        - description: >-
            Workspace slug. Overrides subdomain-based workspace resolution when
            provided.
          in: header
          name: X-Tenant
          required: false
          schema:
            example: acme
            type: string
        - description: Optional request correlation ID echoed back in the response.
          in: header
          name: X-Request-ID
          required: false
          schema:
            example: 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - in: query
          name: tenantConnectorTapId
          required: false
          schema:
            description: UUID v4 with automatic base62 encoding for client-facing APIs
            type: string
        - in: query
          name: limit
          required: false
          schema:
            format: double
            maximum: 100
            minimum: 1
            type: number
        - in: query
          name: offset
          required: false
          schema:
            format: double
            minimum: 0
            type: number
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/TenantTableShapeStatsResponse'
                  links:
                    $ref: '#/components/schemas/ResponseLinks'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                  - data
                  - meta
                type: object
          description: Successful response
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: >-
            The request is not valid. `detail` says why. A value that breaks a
            field rule gives the code `WA-VL-001` and an `errors` member that
            names each field.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: The token is missing, malformed, revoked, or expired.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: >-
            The token cannot make this request. For example, the roles of its
            owner do not allow the operation.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: The request failed on the server.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
      security:
        - bearerAuth: []
      x-codeSamples:
        - label: TypeScript SDK
          lang: typescript
          source: |-
            import { WebApiSDK } from "@parable-platform/web-api-sdk";

            const sdk = new WebApiSDK({
              baseUrl: process.env.PARABLE_API_URL!,
              auth: { token: process.env.PARABLE_API_TOKEN! },
              requestInterceptor: (config) => ({
                ...config,
                headers: { ...config.headers, "X-Tenant": process.env.PARABLE_WORKSPACE! },
              }),
            });

            const query = {};
            const result = await sdk.catalog.tableShapeStats(
              query
            );
        - label: Python SDK
          lang: python
          source: >-
            import os


            from parable_web_api_sdk import ClientConfig, WebApiSDK


            sdk = WebApiSDK(
                ClientConfig(
                    base_url=os.environ["PARABLE_API_URL"],
                    auth_token=os.environ["PARABLE_API_TOKEN"],
                    default_headers={"X-Tenant": os.environ["PARABLE_WORKSPACE"]},
                )
            )


            result = sdk.catalog.table_shape_stats(tenant_connector_tap_id=None,
            limit=None, offset=None)
        - label: Rust SDK
          lang: rust
          source: >-
            use parable_web_api_sdk::{namespaces, ClientConfig, RequestOptions,
            WebApiSdk};


            let sdk = WebApiSdk::new(ClientConfig::with_base_url(
                std::env::var("PARABLE_API_URL")?,
                Some(std::env::var("PARABLE_API_TOKEN")?),
                None,
            ))?;

            let options = RequestOptions::with_header("X-Tenant",
            std::env::var("PARABLE_WORKSPACE")?, None, None);


            let query = namespaces::catalog::TableShapeStatsQueryParams {
                tenant_connector_tap_id: None,
                limit: None,
                offset: None,
            };

            let result = sdk.catalog.table_shape_stats(
                Some(&query),
                Some(&options)
            ).await?;
        - label: Go SDK
          lang: go
          source: "sdk, err := webapisdk.New(webapisdk.SDKConfig{\n\tBaseURL: os.Getenv(\"PARABLE_API_URL\"),\n\tAuth:    &webapisdk.AuthConfig{Token: os.Getenv(\"PARABLE_API_TOKEN\")},\n\tRequestInterceptor: func(ctx context.Context, req *http.Request) error {\n\t\treq.Header.Set(\"X-Tenant\", os.Getenv(\"PARABLE_WORKSPACE\"))\n\t\treturn nil\n\t},\n})\nif err != nil {\n\treturn err\n}\n\nquery := &namespaces.CatalogTableShapeStatsQueryParams{}\nresult, err := sdk.CatalogNamespace.TableShapeStats(ctx, query)"
components:
  schemas:
    TenantTableShapeStatsResponse:
      description: One page of the latest shape statistics of the Workspace's tables.
      properties:
        nextOffset:
          description: The offset of the next page, or null when this page is the last.
          format: double
          nullable: true
          type: number
        stats:
          items:
            $ref: '#/components/schemas/TableShapeStats'
          type: array
        statsVersion:
          type: string
        tenantId:
          description: UUID v4 with automatic base62 encoding for client-facing APIs
          pattern: >-
            ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          type: string
      required:
        - tenantId
        - statsVersion
        - stats
      type: object
    ResponseLinks:
      properties:
        first:
          nullable: true
          type: string
        last:
          nullable: true
          type: string
        next:
          nullable: true
          type: string
        prev:
          nullable: true
          type: string
      type: object
    ResponseMeta:
      properties:
        requestId:
          description: Unique identifier for the request
          type: string
        totalCount:
          description: Total count of items for paginated responses
          nullable: true
          type: integer
      required:
        - requestId
      type: object
    ProblemDetails:
      description: An error response in the Problem Details format (RFC 9457).
      properties:
        code:
          description: The stable error code, when the problem has one.
          example: WA-VL-001
          type: string
        detail:
          description: What went wrong with this request.
          type: string
        details:
          description: >-
            Structured facts about the refusal, such as the entity or the path
            it concerns. Only some refusals have it.
        errors:
          description: >-
            The fields or filters that failed validation. Only a validation or
            filter error has it.
        requestId:
          description: >-
            The ID of the request, when the problem has one. The `X-Request-ID`
            response header always has it.
          type: string
        status:
          description: The HTTP status code.
          example: 400
          type: integer
        title:
          description: A short summary, usually the text of the HTTP status.
          example: Bad Request
          type: string
        type:
          description: >-
            The problem type. It is `about:blank`: the status and `code`
            identify the problem.
          example: about:blank
          type: string
      required:
        - type
        - title
        - status
        - detail
      type: object
    TableShapeStats:
      description: |-
        Latest shape snapshot of a Tap's table: its size and per-column
        statistics, from the table's last maintenance run.
      properties:
        capturedAt:
          description: Wall-clock timestamp the snapshot was captured.
          format: date-time
          type: string
        columnCount:
          description: >-
            Signed 64-bit integer; range bounded by JavaScript's safe-integer
            ceiling.
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        columns:
          description: Per-column entries. Order matches the contract outputSchema.
          items:
            $ref: '#/components/schemas/ColumnShapeStats'
          type: array
        distinctCountsExact:
          description: >-
            When false, distinct counts in ColumnShapeStats are approximate:
            every

            counted column uses HyperLogLog (`approx_distinct`) so the count's

            memory does not grow with the table. True only when no

            column was counted.
          type: boolean
        loadType:
          description: >-
            A label on snapshots that Parable converted from older history, so
            SPC

            can leave them out. Empty on other snapshots.
          nullable: true
          type: string
        rowCount:
          description: Dataset-level metrics.
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        runDate:
          description: >-
            Calendar date, normalized to ISO 'YYYY-MM-DD'. Accepts ISO
            ('2025-01-01'), slash-separated ('2025/01/15', '01/15/2025'),
            named-month ('January 15, 2025', 'Jan 15, 2025'), and full RFC3339
            datetime (the time portion is dropped).
          format: date
          maxLength: 40
          type: string
        runId:
          description: >-
            Run identity. runId is the maintenance run UUID. runDate is the
            logical

            date the run targets in YYYY-MM-DD form.
          pattern: >-
            ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          type: string
        sampledRowCount:
          description: >-
            Rows the scan read when the run sampled the table, or null when it
            read

            every row. A table with more rows than the scan limit is read
            through a

            deterministic sample of its files. rowCount, totalByteSize, and each

            column's null count and min/max still describe the whole table.
            Every

            other column field is estimated from the sample, and distinctCount
            is

            null.
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          nullable: true
          type: integer
        snapshotId:
          description: |-
            Stable identity for this snapshot. Equal to the maintenance run UUID
            for the row that produced it; two reads of the same row return the
            same snapshotId.
          pattern: >-
            ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          type: string
        storageUri:
          description: Where the table's data is stored.
          format: uri
          maxLength: 4096
          pattern: ^[a-zA-Z][a-zA-Z0-9+.-]*://[^\s]+$
          type: string
        tapContractId:
          description: >-
            The Tap this snapshot describes (provider connection.id). Null on
            some

            older snapshots.
          nullable: true
          pattern: >-
            ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          type: string
        totalByteSize:
          description: >-
            Total uncompressed byte size of the table's data at capture time.
            Null

            when the size cannot be determined.
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          nullable: true
          type: integer
      required:
        - snapshotId
        - runId
        - runDate
        - capturedAt
        - rowCount
        - columnCount
        - distinctCountsExact
        - storageUri
        - columns
      type: object
    ColumnShapeStats:
      description: |-
        Per-column snapshot. Embedded in TableShapeStats; not stored
        independently.
      properties:
        arrowType:
          description: |-
            Arrow physical type for the column, in Arrow's display form (e.g.
            "Int64", "Utf8", "Timestamp(Microsecond, Some(\\"UTC\\"))").
          type: string
        avg:
          description: >-
            Numeric-only summaries. Null for non-numeric columns. q25, q50 and
            q75

            are approximate percentiles.
          format: double
          nullable: true
          type: number
        columnName:
          description: Column name as it appears in the contract's outputSchema.
          type: string
        distinctCount:
          description: >-
            Distinct count. Exactness governed by

            TableShapeStats.distinctCountsExact. Null when the column type does

            not support a distinct count (nested List/Struct/Map/Union), for

            engine-owned columns, and when the run sampled the table

            (TableShapeStats.sampledRowCount); absent must not be treated as 0
            by

            quality rules or SPC series.
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          nullable: true
          type: integer
        maxValue:
          nullable: true
          type: string
        minValue:
          description: >-
            Min / max as ISO-string-cast values to keep the response
            JSON-friendly.

            Parse a numeric column's values as numbers. Null when the column has
            zero

            non-null rows.
          nullable: true
          type: string
        nonNullCount:
          description: Non-null row count for the column. Equals rowCount minus null count.
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        nullPct:
          description: >-
            Null percentage in [0.0, 100.0], rounded to two decimals to match
            the

            shape_capture writer's behaviour.
          format: double
          type: number
        parableScalar:
          description: >-
            The Parable scalar from the contract outputSchema for this column

            (canonical name like "Identity.UUID" or "Generic.Int64"). Null when

            the contract outputSchema does not declare a Parable scalar for the

            column (the Arrow type in `arrowType` is the only signal in that
            case).
          maxLength: 128
          minLength: 3
          nullable: true
          pattern: ^[A-Z][A-Za-z0-9]*\.[A-Z][A-Za-z0-9]*$
          type: string
        q25:
          format: double
          nullable: true
          type: number
        q50:
          format: double
          nullable: true
          type: number
        q75:
          format: double
          nullable: true
          type: number
        std:
          format: double
          nullable: true
          type: number
        validationFailureCount:
          description: >-
            Count and percentage of values that failed scalar/contract
            validation for

            this column during the latest maintenance capture.
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        validationFailurePct:
          format: double
          type: number
      required:
        - columnName
        - arrowType
        - nonNullCount
        - nullPct
        - validationFailureCount
        - validationFailurePct
      type: object
  headers:
    X-Request-ID:
      description: >-
        The ID of the request. It is the `X-Request-ID` value that you sent, or
        an ID that the server made. Give it when you report a problem.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      description: >-
        A personal access token, which starts with `pat_`. A Parable token can
        call each operation that the roles of its owner allow. An MCP token can
        call only the read operations that are open to agents. A SQL token does
        not work on this API.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.