---
title: "Probe a connection"
method: POST
path: "/v1/connectors/connections/{connectionId}/health"
tags: ["Connectors"]
---

# Probe a connection

`POST /v1/connectors/connections/{connectionId}/health`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/connectors/connections/{connectionId}/health`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.spacefast.com/v1/auth/oauth2/authorize`, token URL `https://api.spacefast.com/v1/auth/oauth2/token`; client credentials, token URL `https://api.spacefast.com/v1/auth/oauth2/token`, scopes: `connectors:read`)

Runs the connector's declared health check against the stored credential and reports what came back. It only reports: an expired token refreshes on its own.

## Path parameters

- `connectionId` string, required: Connection id (`cxn_`).

## Query parameters

- `team` string: Team id or slug to act for. Required only when the credential could act for more than one team.

## Response `200`

Response for status 200

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` object, required: A live probe of one connection. Token refresh happens automatically; this only reports.
    - `connectionId` string, required
    - `status` 'pending_authorization' | 'active' | 'degraded' | 'needs_reauth' | 'revoked', required: State after this probe.
    - `reachable` boolean, required: Whether the provider answered.
    - `latencyMs` integer, nullable, required: Round trip of the probe; null when it never got an answer.
    - `detail` string, nullable, required: What went wrong, when something did.
    - `toolCount` integer, required: Tools reachable right now.
    - `checkedAt` string, date-time, required

## Other responses

- `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

---

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