Skip to main content
GET
get-connection

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

The connection id.

Query Parameters

wait
boolean
timeout
integer
default:30
Required range: 1 <= x <= 60

Response

200 - application/json

Read a single connection by id or connection key, including its current status.

id
string
required

Internal database ID of the element. Assigned by the API; unique per element.

name
string
required
status
enum<string>
required

Lifecycle status. broken is reserved for provider-confirmed credential or configuration rejection.

Available options:
connected,
broken,
disconnecting,
disconnected
credentialsError
object | null
required

Provider-confirmed credential or configuration rejection. Non-null if and only if status is broken.

consecutiveRefreshFailuresCount
integer
required

Consecutive scheduled credential-refresh failures, used only for backoff arithmetic.

Required range: 0 <= x <= 9007199254740991
tenantId
string
ownerName
string | null
type
enum<string>
Available options:
connector,
mcp,
browser
key
string
grantedScopes
string[]
providerPermissionChecks
object[]
connected
boolean

Whether the connection is authenticated and usable. Projection of status === "connected".

hasDocs
boolean
docsCount
number
docsSummary
string
state
enum<string>

Shared element-state projection of the connection lifecycle and its overlays.

Available options:
BUILDING,
CLIENT_ACTION_REQUIRED,
CONFIGURATION_ERROR,
SETUP_FAILED,
READY,
DISCONNECTING
errors
object[]

Validation or setup errors when state is not READY.

connectorId
string
externalAppId
string
connectorVersion
string
authOptionKey
string
oauthClientId
string
oauthClientVersionId
string
oauthClientName
string
createdAt
string
updatedAt
string
nextCredentialsRefreshAt
string

When the connection credentials are next scheduled for proactive refresh.

canTest
boolean

Whether the connection supports a connectivity test through its connector.

browserProvider
enum<string>
Available options:
browserbase,
puppeteer
canRefreshCredentials
boolean

Whether the connection credentials can be refreshed through its connector refresh flow.

archivedAt
string

When the connection was archived (soft-deleted).

isDeactivated
boolean

True when the connection or an ancestor was deactivated; a deactivated connection has no state.

meta
object
buildingAgentSessionId
string

Session ID for building the element via intent-based endpoints (create/update with intent). Present when state is BUILDING.

ask
object

The next connection step, projected from lifecycle state.

logoUri
string

Resolved app logo for this element (integration -> connector -> external app -> favicon).

input
object

Connect-form fields for this connection. Credential-carrying fields report { "set": true } presence only; their values are never returned.

connectorParameters
object

Connector parameters for this connection. Each field reports { "set": true } presence only; values are never returned.

credentialsSchema
object

Shape of this connection’s stored credentials: field names, types, and descriptions, never values. Use a field name here as the credential path when binding a credential into a command with the with-credentials CLI tool.