---
title: "Get connector statistics"
method: GET
path: "/connectors/{connectorId}/stats"
tags: ["Connector Instances"]
---

# Get connector statistics

`GET /connectors/{connectorId}/stats`

## Request

- Base URL: `https://app.pipeshub.com/api/v1`
- URL: `https://app.pipeshub.com/api/v1/connectors/{connectorId}/stats`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `/api/v1/oauth2/authorize`
    - Client credentials
    - Token URL: `/api/v1/oauth2/token` scopes: `connector:read`

Retrieve record counts of a connector instance, in total and per record
type, broken down by indexing status. The ID of a knowledge base is
accepted too (a knowledge base is stored as a connector instance of type
<code>KB</code>); its stats report <code>origin: COLLECTION</code>.<br><br>
<b>Who can read them:</b> the creator of the instance and, for a team
instance, org admins. Stats use the same read gate as
<code>GET /connectors/{connectorId}</code>: anyone else, including an
admin reading another user's personal instance, gets <code>404</code>
("This connector was removed, or you no longer have access. ..."), so
the instance's existence is not confirmed.

An OAuth token holding `kb:read` instead of `connector:read` passes the scope check too.

## Path parameters

- `connectorId` string, required

## Response `200`

Connector statistics

- ConnectorStats: Statistics for a connector's records
  - `success` boolean, required
  - `data` object, required
    - `orgId` string, required
    - `connectorId` string, required
    - `origin` 'CONNECTOR' | 'COLLECTION', required: Where the records come from; `CONNECTOR` for a connector.
    - `stats` object, required
      - `total` integer, required: Records synced from the connector
      - `indexingStatus` ConnectorIndexingStatusCounts, required: Number of records in each indexing status.
        - `NOT_STARTED` integer
        - `PAUSED` integer
        - `IN_PROGRESS` integer
        - `COMPLETED` integer
        - `FAILED` integer
        - `FILE_TYPE_NOT_SUPPORTED` integer
        - `AUTO_INDEX_OFF` integer
        - `EMPTY` integer
        - `ENABLE_MULTIMODAL_MODELS` integer
        - `QUEUED` integer
        - `SKIPPED` integer
        - `PASSWORD_PROTECTED` integer
      - `extractionStatus` object: Record counts by classification (`classify` stage) status.
      - `entitiesStatus` object: Record counts by named-entity extraction (`entities` stage) status, read from each record's `entities` stage state on its current revision. A record with no such state is not counted.
    - `byRecordType` object[], required: The same counts per record type; empty before the first sync.
      - `recordType` string, required
      - `total` integer, required
      - `indexingStatus` ConnectorIndexingStatusCounts, required: Number of records in each indexing status.
        - `NOT_STARTED` integer
        - `PAUSED` integer
        - `IN_PROGRESS` integer
        - `COMPLETED` integer
        - `FAILED` integer
        - `FILE_TYPE_NOT_SUPPORTED` integer
        - `AUTO_INDEX_OFF` integer
        - `EMPTY` integer
        - `ENABLE_MULTIMODAL_MODELS` integer
        - `QUEUED` integer
        - `SKIPPED` integer
        - `PASSWORD_PROTECTED` integer
      - `extractionStatus` object: Record counts by classification (`classify` stage) status.
      - `entitiesStatus` object: Record counts by named-entity extraction (`entities` stage) status.

## Other responses

- `400`: `connectorId` is not a safe path segment (for example it contains an encoded `/`). Answered before the token is checked. Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
- `401`: Missing or invalid credentials
- `403`: The OAuth client's token lacks the `connector:read` or `kb:read` scope, or the ID is a knowledge base on which the caller has a role other than OWNER, WRITER or READER.
- `404`: No connector instance or knowledge base has this ID, or the caller cannot open it (not the creator, and not an admin of a team instance; another user's personal instance is not found for admins either; a knowledge base the caller has no role on).
- `500`: Internal server error. A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.

## Changes

- **2026-10-28** `dbb5e203b445`: 2 warning, 6 info
  - added the new `COLLECTION` enum value to the `data/origin` response property for the response status `200`
  - added the new `CONNECTOR` enum value to the `data/origin` response property for the response status `200`
  - added the non-success response with the status `400`
  - added the non-success response with the status `500`
  - …4 more
- **2026-10-26** `fc76aa045994`: 4 info
  - added the optional property `data/byRecordType/items/entitiesStatus` to the response with the `200` status
  - added the optional property `data/byRecordType/items/extractionStatus` to the response with the `200` status
  - added the optional property `data/stats/entitiesStatus` to the response with the `200` status
  - added the optional property `data/stats/extractionStatus` to the response with the `200` status
- **2026-10-15** `a44792e4f0e6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/changes/connectors/:connectorId/stats/get.md)

---

[API](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api.md) - [All operations](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/revisions/dbb5e203b445?raw)