> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Connector Status
> Check whether a connector is working, with per-resource health, in one call.
Answers "is this connector working?" in one call. It returns an overall `status` for the connector plus one health entry per configured resource, so a connector that syncs four tables and fails on a fifth reports `degraded` rather than looking healthy.
```bash cURL theme={"dark"}
curl 'https://api.hydradb.com/connectors/{id}/status' \
-H "Authorization: Bearer $HYDRA_DB_API_KEY" \
-H "API-Version: 2"
```
```json 200 theme={"dark"}
{
"connector_id": "{connector_id}",
"provider": "supabase",
"status": "degraded",
"lifecycle": "active",
"sync_status": "idle",
"last_successful_sync_at": "2026-09-28T19:04:10Z",
"last_attempted_sync_at": "2026-09-28T19:04:10Z",
"next_sync_at": "2026-09-28T20:04:10Z",
"error": null,
"resources": [
{
"resource_id": "public.orders",
"display_name": "public.orders",
"status": "ok",
"last_row_count": 42,
"checked_at": "2026-09-28T19:04:09Z"
},
{
"resource_id": "public.invoices",
"display_name": "public.invoices",
"status": "failed",
"last_row_count": 0,
"message": "permission denied for table invoices",
"retryable": false,
"http_status": 403,
"checked_at": "2026-09-28T19:04:09Z",
"action": "Grant the connector's database role read access to this table."
}
]
}
```
## Reading the response
`status` is the overall health. It is the worst of the credential state and every resource's state:
* `healthy`: every resource synced and nothing needs attention.
* `degraded`: the connector is still scheduled but not fully working. At least one resource is failing, the latest sync failed and is being retried, synced documents are failing to index, or no resources are configured. Check `resources[].message`, or `error` when the whole sync failed.
* `failed`: only you can fix it, for example by reconnecting after the provider rejected the credentials, or after a sync failure that will not clear on retry. `error.action` says what to do.
* `checking`: resources were just configured and HydraDB is still testing access to them.
* `paused`: syncing was turned off for this connector. [Resume Connector](/api-reference/v2/endpoint/resume-connector) turns it back on.
* `capped`: a plan limit is pausing syncs. `plan_cap` says which limit.
`lifecycle` and `sync_status` answer a different question: what the connector is doing right now. A connector can be `syncing` and `degraded` at the same time.
For each resource, `status` is the result of its last sync: `ok`, `empty` (ran and found nothing new), `failed`, `checking`, or `unknown`. When a resource fails, `retryable: false` means the provider rejected it and waiting will not help. A resource with `sync_blocked: true` has stopped syncing until you fix the cause in `sync_blocked_reason`.
`acl_warning` on a resource means HydraDB could not read that resource's permissions from the provider. If you set an access rule on the resource, your rule still applies. If you did not, its objects are readable by everyone until the next successful read. Set a rule with [Update Connector Resource](/api-reference/v2/endpoint/update-connector-resource) to restrict it in the meantime.
`page_acl_warning` means restrictions on some individual pages, for example in Confluence, could not be read, so those pages are readable by everyone until a later sync reads them. See [Access Control](/essentials/v2/access-control).
## Related Resources
* [List Connector Resources](/api-reference/v2/endpoint/connector-resources): each resource's configuration and sync cursor
* [Sync Connector](/api-reference/v2/endpoint/sync-connector): start a sync after fixing a failure
* [Update Connector](/api-reference/v2/endpoint/update-connector): reconnect with new credentials when `status` is `failed`
## OpenAPI
````yaml api-reference/v2/openapi.json GET /connectors/{id}/status
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}/status:
get:
tags:
- connectors
summary: Get a connector's health
description: >-
Check whether a connector is working, in one call: an overall `status`
plus one health entry per configured resource. Use it to find a failing
resource or a connector that needs you to reconnect.
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.connectorStatusResponse'
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.connectorStatusResponse:
properties:
connector_id:
description: Connector this resource belongs to.
example: conn_abc123
type: string
error:
anyOf:
- $ref: '#/components/schemas/handler.connectorStatusError'
title: Connector failure
- title: No connector failure
type: 'null'
description: >-
Connector-level failure, such as rejected credentials or a failed
sync. `null` when the connector itself is fine; resource problems
are reported on each resource.
example: null
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_successful_sync_at:
description: RFC3339 timestamp of the last successful sync completion.
example: '2026-07-02T17:00:00Z'
type: string
lifecycle:
description: >-
What the connector is doing now: `reconnect`, `syncing`,
`pending_setup`, `ingesting` or `active`. Independent of `status`.
type: string
next_sync_at:
description: RFC3339 timestamp when the next scheduled sync will run.
example: '2026-07-02T18:00:00Z'
type: string
plan_cap:
$ref: '#/components/schemas/handler.planCapView'
example:
message: Success
provider:
description: >-
External provider being synced (e.g. `slack`, `github`, `linear`,
`notion`, `gmail`).
example: slack
type: string
resources:
description: >-
One entry per configured resource with its own health. Always an
array, empty when no resources are configured.
example:
- display_name: general
http_status: 1
last_row_count: 1
message: Success
resource_id: C0123456789
retryable: true
status: completed
sync_blocked: true
items:
$ref: '#/components/schemas/handler.connectorResourceStatus'
type: array
uniqueItems: false
status:
description: >-
Overall health: `healthy`, `degraded` (partly failing, still
retrying), `failed` (you must act, e.g. reconnect), `checking`
(testing new resources), `paused`, or `capped` (a plan limit paused
syncs).
example: healthy
type: string
sync_status:
description: >-
`syncing` while a sync is running, otherwise `idle`. Independent of
`status`: a connector can be syncing and degraded at once.
example: idle
type: string
type: object
handler.ErrorResponse:
properties:
data:
description: Always `null` on this error response.
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: false
type: boolean
type: object
handler.connectorStatusError:
description: >-
Connector-level failure, such as rejected credentials or a failed sync.
`null` when problems are limited to individual resources, which carry
their own messages.
properties:
action:
description: What to do to fix the failure, when there is something you can do.
type: string
detected_at:
description: When the failure was detected (RFC 3339).
type: string
message:
description: What went wrong, in the provider's or HydraDB's words.
example: The provider rejected the stored credentials.
type: string
retryable:
description: >-
`true` when the failure may clear on its own. `false` means only you
can fix it, for example by reconnecting.
example: true
type: boolean
type: object
handler.planCapView:
description: The plan limit that is currently stopping syncs.
properties:
message:
description: >-
Human-readable explanation of the limit, the same message the ingest
endpoints return.
example: Success
type: string
meter:
description: 'Which limit was reached: `tokens` or `storage`.'
type: string
plan:
description: Plan the organization is on.
type: string
type: object
handler.connectorResourceStatus:
properties:
acl_warning:
description: >-
Why this resource's permissions could not be read. Without an access
rule of yours, its objects are readable by everyone meanwhile; with
one, your rule applies. Clears on the next successful read.
type: string
acl_warning_at:
description: >-
When `acl_warning` last changed (RFC 3339). An unchanged warning
keeps its original time.
type: string
action:
description: What to do to fix this resource, when there is something you can do.
type: string
checked_at:
description: When this resource's health was last recorded (RFC 3339).
type: string
display_name:
description: Human-readable name for this resource.
example: general
type: string
http_status:
description: HTTP status code the provider returned, when one was reported.
example: 1
type: integer
last_row_count:
description: Number of records the last sync produced for this resource.
example: 1
type: integer
message:
description: The provider's explanation when `status` is `failed`.
example: Success
type: string
page_acl_warning:
description: >-
Set when page-level restrictions in this resource (for example
Confluence pages) could not be resolved, so those pages are readable
by everyone. Clears after a clean full sync.
type: string
page_acl_warning_at:
description: When `page_acl_warning` last changed (RFC 3339).
type: string
resource_id:
description: Resource identifier from the Discover endpoint.
example: C0123456789
type: string
retryable:
description: >-
Present when `status` is `failed`. `false` means the provider
rejected the resource and only you can fix it; `true` means it may
clear on its own.
example: true
type: boolean
status:
description: >-
Result of this resource's last sync: `ok`, `empty` (ran and found
nothing new), `failed`, `checking`, or `unknown` (no sync has
reported yet).
example: ok
type: string
sync_blocked:
description: >-
`true` when syncing of this resource has stopped because the
provider keeps refusing it. `sync_blocked_reason` says why.
example: true
type: boolean
sync_blocked_at:
description: When syncing of this resource was stopped (RFC 3339).
type: string
sync_blocked_reason:
description: >-
The provider's explanation for why this resource is blocked. Present
only while `sync_blocked` is `true`.
type: string
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: always `false`. Read the HTTP status, then `error.code`
and `error.message`.
example: false
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:
description: Version of the API that served the request, for example `2.0.1`.
type: string
latency_ms:
description: Server-side processing time in milliseconds.
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
````