Get Connector

Read one connector’s settings and sync state.

GET /connectors/{id}

cURL

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

200

{
  "connector_id": "{connector_id}",
  "provider": "slack",
  "name": "acme-engineering",
  "database": "acme_corp",
  "collection": "engineering",
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "provider_account_scope": "T12345ACME",
  "custom_instructions": "Prioritize decisions and owners.",
  "lifecycle": "active",
  "status": "active",
  "sync_status": "idle",
  "active_resource_count": 2,
  "sync_interval_seconds": 3600,
  "next_sync_at": "2026-06-01T13:00:00Z",
  "last_successful_sync_at": "2026-06-01T12:05:00Z"
}

Returns one connector: where it syncs to, its connector-level custom_instructions, its sync interval, and its sync state.

lifecycle is the field to read for what the connector is doing: pending_setup (no resources configured), ingesting (first sync not finished), syncing, active, paused, or reconnect (the provider rejected the credentials). status is deprecated and always active. For per-resource health, use Get Connector Status.

cURL

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

200

{
  "connector_id": "{connector_id}",
  "provider": "slack",
  "name": "acme-engineering",
  "database": "acme_corp",
  "collection": "engineering",
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "provider_account_scope": "T12345ACME",
  "custom_instructions": "Prioritize decisions and owners.",
  "lifecycle": "active",
  "status": "active",
  "sync_status": "idle",
  "active_resource_count": 2,
  "sync_interval_seconds": 3600,
  "next_sync_at": "2026-06-01T13:00:00Z",
  "last_successful_sync_at": "2026-06-01T12:05:00Z"
}

Errors

• 404: no connector with this id in your workspace.

Related Resources

• Update Connector: change these settings
• List Connector Resources: the connector’s resources
• Get Connector Status: per-resource health

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

active_resource_count · integer

Number of active resources on this connector. Zero means none are configured yet, and lifecycle reads pending_setup.

Example:

1

auth_type · string

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

Example:

"api_token"

collection · string

Default collection for synced data; a resource can override it. Formerly sub_tenant_id, which is still returned with the same value.

Example:

"team_docs"

connector_id · string

Unique identifier of the connector.

Example:

"conn_abc123"

custom_instructions · string

Instructions that steer how this connector's synced documents are ingested and indexed. Up to 4000 characters; changes apply from the next sync.

database · string

Database that receives the synced data. Formerly tenant_id, which is still returned with the same value.

Example:

"acme_corp"

documents_dispatched · integer

Running total of objects sent for ingestion. It shows data is moving, not the indexed count: updates count again and deletes are not subtracted.

Example:

1

first_data_dispatched_at · string

RFC3339 timestamp of the first sync that sent at least one object for ingestion. Empty until then.

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

Current state: pending_setup (no active resources), ingesting (first sync unfinished), syncing, active, paused, or reconnect (credentials rejected or connector blocked).

name · string

Human-readable label for this connector.

Example:

"general"

needs_reauth · boolean

True when the provider rejected the OAuth refresh token. Reconnect the account to resume syncing; clears on the next successful token refresh.

Example:

true

needs_reauth_at · string

RFC3339 timestamp when needs_reauth was set.

needs_reauth_reason · string

Why the provider rejected the OAuth grant, when needs_reauth is true.

next_sync_at · string

RFC3339 timestamp when the next scheduled sync will run.

Example:

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

paused · boolean

True while the connector is paused. Scheduled and manual syncs are both refused until it is resumed; each resource then continues from where it stopped.

Example:

true

paused_at · string

RFC3339 timestamp when the connector was paused.

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). Set a distinct value per account when you connect several accounts of one provider, so their objects cannot collide.

Example:

"T12345ACME"

resources_pending_first_sync · integer

Number of active resources that have not completed their first successful sync. While above zero, lifecycle reads ingesting.

Example:

1

status · string · deprecated

Deprecated: always active. Read lifecycle for what the connector is doing.

Example:

"active"

sub_tenant_id · string · deprecated

Deprecated: use collection.

Example:

"sub_tenant_4567"

sync_blocked · boolean

True when a failure retrying cannot fix, such as rejected credentials, stopped scheduled syncs. Updating credentials or configuration clears it.

Example:

true

sync_blocked_at · string

RFC3339 timestamp when sync_blocked was set.

sync_blocked_reason · string

Error that blocked the connector, when sync_blocked is true. Up to 1000 characters.

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

syncing while a sync is running, otherwise idle.

Example:

"idle"

tenant_id · string · deprecated

Deprecated: use database.

Example:

"tenant_1234"