Get Connector

Fetch metadata and status for a single connector.

GET /connectors/{id}

cURL

curl 'https://api.hydradb.com/connectors/{connector_id}' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

200

{
  "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
}

cURL

curl 'https://api.hydradb.com/connectors/{connector_id}' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

Path parameters

Name	Description
id	Connector UUID returned by POST /connectors.

200

{
  "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
}

Related Resources

• List Connectors
• Connector Resources - see per-resource sync state

Authorizations

Authorization · string · header · required

API key sent as a Bearer token: "Bearer prefix.secret"

Path Parameters

id · string · required

Connector ID

Example:

"HydraDoc1234"

Response

200

application/json

OK

acl_changes_cursor · string

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

active_resource_count · integer

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

auth_type · string

Authentication method for the provider connection (e.g. api_token, oauth).

Example:

"api_token"

collection · string

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"

connector_id · string

Connector this resource belongs to.

Example:

"conn_abc123"

custom_instructions · string

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.

database · string

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"

documents_dispatched · integer

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

first_data_dispatched_at · string

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

last_attempted_sync_at · string

RFC3339 timestamp of the most recent sync attempt (successful or not).

Example:

"2026-07-02T17:00:00Z"

last_error · string

Error message from the most recent failed sync, empty string when no error.

Example:

""

last_successful_sync_at · string

RFC3339 timestamp of the last successful sync completion.

Example:

"2026-07-02T17:00:00Z"

lifecycle · string

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.

name · string

Human-readable label for this resource.

Example:

"general"

needs_reauth · boolean

Example:

true

needs_reauth_at · string

needs_reauth_reason · string

next_sync_at · string

RFC3339 timestamp when the next scheduled sync will run.

Example:

"2026-07-02T18:00:00Z"

paused · boolean

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

paused_at · string

paused_next_sync_at · string

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.

provider · string

External provider being synced (e.g. slack, github, linear, notion, gmail).

Example:

"slack"

provider_account_scope · string

Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Must be distinct across connectors for the same provider.

Example:

"T12345ACME"

resources_pending_first_sync · integer

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

status · string

Current lifecycle or processing state.

Example:

"completed"

sub_tenant_id · string · deprecated

Example:

"sub_tenant_4567"

sync_blocked · boolean

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

sync_blocked_at · string

sync_blocked_reason · string

sync_cycles_completed · integer

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

sync_engine · string

SyncEngine is "classic" (default, empty treated as classic) or "moveit". See the SyncEngine* constants; the scheduler branches on it.

sync_interval_seconds · integer

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

sync_status · string

Current sync operation state (e.g. idle, running).

Example:

"idle"

tenant_id · string · deprecated

Example:

"tenant_1234"