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

# Get Connector

> Fetch metadata and status for a single connector.

<RequestExample>
  ```bash cURL theme={null}
  curl 'https://api.hydradb.com/connectors/{connector_id}' \
    -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
    -H "API-Version: 2"
  ```
</RequestExample>

## Path parameters

| Name | Description                                    |
| ---- | ---------------------------------------------- |
| `id` | Connector UUID returned by `POST /connectors`. |

<ResponseExample>
  ```json 200 theme={null}
  {
    "connector_id": "{connector_id}",
    "provider": "slack",
    "name": "acme-engineering",
    "tenant_id": "acme_corp",
    "sub_tenant_id": "engineering",
    "provider_account_scope": "T12345ACME",
    "status": "active",
    "sync_status": "idle",
    "next_sync_at": "2026-06-01T13:00:00Z",
    "sync_interval_seconds": 3600
  }
  ```
</ResponseExample>

<div className="api-before-related-resources" />

## Related Resources

* [List Connectors](/api-reference/v2/endpoint/list-connectors)
* [Connector Resources](/api-reference/v2/endpoint/connector-resources)  -  see per-resource sync state


## OpenAPI

````yaml api-reference/v2/openapi.json GET /connectors/{id}
openapi: 3.1.0
info:
  contact:
    email: support@hydradb.com
    name: HydraDB Support
  description: >-
    HydraDB Application API — knowledge ingestion, search, and memory
    management.
  license:
    name: Proprietary
  title: HydraDB Application API
  version: 0.1.0
servers:
  - description: Production server
    url: https://api.hydradb.com
security: []
externalDocs:
  description: ''
  url: ''
paths:
  /connectors/{id}:
    get:
      tags:
        - connectors
      summary: Get a connector
      description: Fetch a single connector by ID.
      parameters:
        - description: Connector ID
          in: path
          name: id
          required: true
          schema:
            example: HydraDoc1234
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.connectorAPIView'
          description: OK
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
        - BearerAuth: []
components:
  schemas:
    handler.connectorAPIView:
      properties:
        acl_changes_cursor:
          description: >-
            ACLChangesCursor is the provider permission-change feed's persisted

            cursor (PRO-1684; e.g. the Drive changes.list page token). Empty
            means

            uninitialized: the next cycle fetches a baseline and starts from
            now.

            Advanced ONLY after every reported change was applied, so a failed

            apply replays the same changes next cycle (at-least-once; the writes

            are idempotent full replacements).
          type: string
        active_resource_count:
          description: >-
            ActiveResourceCount mirrors the number of non-disabled resource rows
            so

            list responses can distinguish "no resources configured yet"

            (pending_setup) without a per-connector resources query.
          example: 1
          type: integer
        auth_type:
          description: >-
            Authentication method for the provider connection (e.g. `api_token`,
            `oauth`).
          example: api_token
          type: string
        collection:
          description: >-
            Collection scope. Defaults to the default collection when omitted.
            Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still
            accepted (deprecated).
          example: team_docs
          type: string
        connector_id:
          description: Connector this resource belongs to.
          example: conn_abc123
          type: string
        custom_instructions:
          description: >-
            CustomInstructions is optional free-text guidance applied when this

            connector's documents are ingested: it steers how content is
            interpreted

            and indexed. Max 4000 characters; changes apply from the next sync
            cycle.
          type: string
        database:
          description: >-
            Database/Collection are the canonical v2 names for the deprecated

            tenant_id/sub_tenant_id wire fields. They mirror the same values so
            a v2

            client sees the canonical names on responses while a legacy client
            keeps

            reading tenant_id/sub_tenant_id. Not persisted (dynamodbav:"-"): the
            store

            builds items from tenant_id/sub_tenant_id and mirrors these on load.
            They

            are populated at every construction point (toConnector,
            connectorFromItem)

            rather than via MarshalJSON so Temporal's JSON data converter
            round-trips

            Connector activity inputs without spuriously populating them.
          example: acme_corp
          type: string
        documents_dispatched:
          description: >-
            DocumentsDispatched is the running total of objects handed to
            ingestion

            across all completed cycles. It is dispatch *activity*, not an
            indexed

            count: upserts count every time they change, deletes are never

            subtracted, and an activity retry can double-count. Suitable as an

            is-data-moving signal, never as "N documents indexed".
          example: 1
          type: integer
        first_data_dispatched_at:
          description: >-
            FirstDataDispatchedAt is set once, by the first completed cycle that

            dispatched more than zero objects. Its presence is what proves the

            pipeline end to end; after it is set, an empty cycle is "nothing
            changed

            at the source", not "still ingesting".
          type: string
        last_attempted_sync_at:
          description: >-
            RFC3339 timestamp of the most recent sync attempt (successful or
            not).
          example: '2026-07-02T17:00:00Z'
          type: string
        last_error:
          description: >-
            Error message from the most recent failed sync, empty string when no
            error.
          example: ''
          type: string
        last_successful_sync_at:
          description: RFC3339 timestamp of the last successful sync completion.
          example: '2026-07-02T17:00:00Z'
          type: string
        lifecycle:
          description: >-
            Lifecycle is the derived what-is-it-doing-now field and the one
            status

            clients should read (PRO-1565): reconnect | syncing | pending_setup
            |

            ingesting | active. The embedded `status` field is a
            scheduler-internal

            constant ("active" always) kept only for compatibility, and
            `sync_status`

            is the narrower mid-cycle indicator. Computed at the HTTP boundary
            from

            the connector's stored facts, never persisted, so it cannot disagree

            with them.
          type: string
        name:
          description: Human-readable label for this resource.
          example: general
          type: string
        needs_reauth:
          example: true
          type: boolean
        needs_reauth_at:
          type: string
        needs_reauth_reason:
          type: string
        next_sync_at:
          description: RFC3339 timestamp when the next scheduled sync will run.
          example: '2026-07-02T18:00:00Z'
          type: string
        paused:
          description: >-
            Paused marks a connector its owner deliberately stopped (PRO-1762).
            It

            parks next_sync_at as SyncBlocked does, but stays a separate field:

            blocking clears itself once the cause is fixed, whereas only an
            explicit

            resume lifts a pause. Resources keep their committed
            provider_cursor, so

            resuming continues from where each stream stopped.
          example: true
          type: boolean
        paused_at:
          type: string
        paused_next_sync_at:
          description: >-
            PausedNextSyncAt preserves the schedule the pause displaced. Resume
            makes

            the connector due immediately, so this is read back only to recover
            from

            a pause applied by mistake.
          type: string
        provider:
          description: >-
            External provider being synced (e.g. `slack`, `github`, `linear`,
            `notion`, `gmail`).
          example: slack
          type: string
        provider_account_scope:
          description: >-
            Identifier for the external account (e.g. Slack workspace ID, GitHub
            org name). Must be distinct across connectors for the same provider.
          example: T12345ACME
          type: string
        resources_pending_first_sync:
          description: >-
            ResourcesPendingFirstSync counts active resources whose
            provider_cursor

            is still empty — resources that have never been successfully pulled.

            MOVEIT commits provider_cursor after every successful pull (even a

            zero-row one), so this self-clears one cycle after each resource
            first

            syncs. Recomputed by the MOVEIT sync workflow each cycle and by the

            resource-mutating handlers, so a resource added to a long-active

            connector re-enters the ingesting state.
          example: 1
          type: integer
        status:
          description: Current lifecycle or processing state.
          example: completed
          type: string
        sub_tenant_id:
          deprecated: true
          example: sub_tenant_4567
          type: string
          x-deprecated: 'true'
        sync_blocked:
          description: >-
            NeedsReauth is set by MOVEIT's OAuth refresh sweep when the provider
            has

            rejected the connector's refresh token (`invalid_grant` — expired,
            revoked,

            or, for a provider with single-use tokens, already spent).


            It is deliberately distinct from LastError, which records a *sync*
            failure.

            This is the one failure class no amount of retrying resolves: the
            stored

            grant is gone and only the tenant can mint a new one. Surfacing it
            as its

            own field is what lets a client show "reconnect" instead of a
            generic

            "sync failed", and the sweep clears it automatically on the next
            successful

            rotation, so a client can trust the absence of the flag as much as
            its

            presence.


            Only ever set on OAuth-bundle connectors. A connector authenticated
            with a

            static token or with client credentials (X posts: see the
            `client_id` /

            `client_secret` inputs on tap-twitter) has no refresh token and
            therefore

            cannot reach this state at all — which is the reason to prefer that
            shape

            where a provider offers it.

            SyncBlocked marks a connector stopped by a terminal failure — one no

            retry can fix. The scheduler skips it and next_sync_at is parked a

            century out; only a credential or config update clears it. Distinct
            from

            NeedsReauth, which is the OAuth sweep's own narrower signal: this
            covers

            any provider rejection of the stored credentials, including static
            keys

            that have no refresh token to sweep.
          example: true
          type: boolean
        sync_blocked_at:
          type: string
        sync_blocked_reason:
          type: string
        sync_cycles_completed:
          description: >-
            SyncCyclesCompleted counts successfully completed sync cycles.
            Bounded

            use only: it lets DeriveLifecycle stop reporting "ingesting" after a
            few

            clean-but-empty cycles on a source that genuinely has nothing to
            pull.
          example: 1
          type: integer
        sync_engine:
          description: >-
            SyncEngine is "classic" (default, empty treated as classic) or
            "moveit".

            See the SyncEngine* constants; the scheduler branches on it.
          type: string
        sync_interval_seconds:
          description: >-
            How frequently the scheduler triggers incremental syncs, in seconds.
            Bounded per provider; send 0 or omit to use the provider default.
            Change it later with PATCH /connectors/{id}.
          example: 3600
          type: integer
        sync_status:
          description: Current sync operation state (e.g. `idle`, `running`).
          example: idle
          type: string
        tenant_id:
          deprecated: true
          example: tenant_1234
          type: string
          x-deprecated: 'true'
      type: object
    handler.ErrorResponse:
      properties:
        data: {}
        detail:
          $ref: '#/components/schemas/handler.ErrorDetail'
          description: Structured error detail with code, message, and deprecation hints.
          example:
            deprecated: true
            deprecated_field: tenant_id
            error_code: VALIDATION_ERROR
            message: Request validation failed
            preferred_field: database
        error:
          $ref: '#/components/schemas/handler.apiError'
          description: Error message, empty string on success.
          example:
            code: DATABASE_NOT_FOUND
            message: Database not found
        meta:
          $ref: '#/components/schemas/handler.ErrorMeta'
          example:
            latency_ms: 12.3
            request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
        success:
          description: Whether the request succeeded.
          example: true
          type: boolean
      type: object
    handler.ErrorDetail:
      properties:
        deprecated:
          description: Whether this response concerns a deprecated field or route.
          example: true
          type: boolean
        deprecated_field:
          description: The deprecated field name.
          example: tenant_id
          type: string
        error_code:
          description: Machine-readable error classification code.
          example: VALIDATION_ERROR
          type: string
        message:
          description: Human-readable description of the error.
          example: Request validation failed
          type: string
        preferred_field:
          description: The canonical replacement for the deprecated field.
          example: database
          type: string
        success:
          deprecated: true
          description: >-
            Deprecated for API clients: always false on this path, so it carries
            no

            information. To detect a failure read the HTTP status code; for what

            went wrong read the envelope's error.code and error.message, and

            meta.request_id when reporting it. The whole `detail` object is

            deprecated legacy — tagging the field individually so SDK users see
            it

            on the property, not just the container (PRO-1208).
          example: true
          type: boolean
          x-deprecated: 'true'
      type: object
    handler.apiError:
      properties:
        code:
          description: Machine-readable error code (e.g. `DATABASE_NOT_FOUND`).
          example: DATABASE_NOT_FOUND
          type: string
        message:
          description: Human-readable description of the error.
          example: Database not found
          type: string
      type: object
    handler.ErrorMeta:
      properties:
        api_version:
          type: string
        latency_ms:
          example: 12.3
          type: number
        request_id:
          description: Unique identifier for this request, useful for support and tracing.
          example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API key
      description: 'API key sent as a Bearer token: "Bearer prefix.secret"'
      scheme: bearer
      type: http

````