Get a connection

GET/api/connections/{id}

Returns one connection’s details, never its secret.

Needs an API token with the Read permission for connections (connection:read).

Parameters

Path

idRequired · UUID: The connection’s ID.

The same as a row of the list

The same fields as a row of List connections, so workspaceId and orgId are all zeros here too. For the saved values that aren’t secret, get its settings.

Responses

200OK
The connection.
400VALIDATION_ERROR
id isn’t a UUID.
403FORBIDDEN
The token lacks the Read permission for connections.
404NOT_FOUND
No connection with this ID in the token’s workspace. One in another workspace is a 404 too.

Any call can also answer: 401 UNAUTHORIZED · 401 TOKEN_ENDED · 403 TOKEN_SURFACE_OFF · 403 FEATURE_OFF · 403 EMBED_NOT_ALLOWED · 403 EMBED_NOT_AVAILABLE · 403 ACCOUNT_SUSPENDED · 429 RATE_LIMITED · 503 BUSY · 503 PAUSED · 503 SERVICE_UNAVAILABLE. See Errors.

Request

GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs Read for connections
CONNECTION_ID="your-connection-id"

curl "$GORUNNER/api/connections/$CONNECTION_ID" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"

const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const CONNECTION_ID = process.env.CONNECTION_ID;

const res = await fetch(
  `${GORUNNER}/api/connections/${CONNECTION_ID}`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await res.json();

import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
CONNECTION_ID = os.environ["CONNECTION_ID"]

res = requests.get(
    f"{GORUNNER}/api/connections/{CONNECTION_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

Response · 200 OK, shortened

json

{
  "data": {
    "id": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
    "pieceId": "postgres",
    "name": "Warehouse database",
    "authType": "custom",
    "status": "active",
    "lastTestedAt": "2026-10-24T16:00:00Z",
    "account": "warehouse@db.bakery.example:5432/orders",
    "workspaceId": "00000000-0000-0000-0000-000000000000",
    "orgId": "00000000-0000-0000-0000-000000000000",
    "createdBy": "5d8e1f3a-0b6c-4e2d-9f7a-1c3b5e8d2a40",
    "createdAt": "2026-10-20T08:00:00Z",
    "updatedAt": "2026-10-24T16:00:00Z"
  }
}

Every field

It takes no body.

Response · 200 OK

dataobject

A stored credential set for one app. The encrypted credential itself is never present in this object — the model tags it json:"-" — so there is no field here, and no endpoint anywhere, that returns a secret you wrote.

idUUID

The connection’s id. This is the value a workflow step or trigger carries as connectionId to use these credentials.

pieceIdstring

The app these credentials belong to (e.g. seatable, postgres, googlesheets, or the generic oauth2). Fixed at creation and not changeable.

namestring

Human label. Not unique.

authTypestring

Free-text label recording the auth shape. Defaults to api_key when not supplied at creation. Conventionally one of the app’s auth.type values, but NOT validated against the app — treat it as advisory.

statusstring

The last known verdict on these credentials. active = created normally, or the last test passed. pending = an OAuth2 connection that has not completed the authorization flow (no access token yet). unverified = the last test proved nothing because the app has no connection test; credentials are checked on first real use. error = the last test was refused by the provider. expired = a refresh was refused for good — the provider rejected the stored grant or the client (revoked, aged out), or the OAuth app that issued the tokens was replaced or removed; signing in again (Re-authorize) mends it. The test endpoint (and test: true on create or update), the OAuth2 sign-in and a refused refresh set it; an update that sends config resets it to active (pending for a sign-in with no token); a rename leaves it.

One of active, pending, unverified, error, expired.

lastTestedAttime

When the connection was last tested. Absent if never tested.

tokenExpiresAttime

OAuth2 access-token expiry, when known. Refresh happens automatically at run time; there is no manual refresh call.

refreshableboolean

The stored config carries a refresh token, so tokenExpiresAt is when the access token is next RENEWED (on use), not when the connection ends. False for pasted access tokens and API keys. A connection whose refresh the provider refuses for good is marked status: expired on the next refresh attempt and needs signing in again.

managedBystring

Present only on a connection the installation’s partner manages through the embed API. It is read-only here: update, delete and the OAuth2 sign-in answer 403 MANAGED_CONNECTION; test and replace stay open.

One of partner.

workspaceIdUUID

Owning workspace. Populated on the create’s answer; the all-zero UUID on the list, the single read and an update’s answer, which read the row the way the list does and do not select it.

orgIdUUID

Owning organization. Same caveat as workspaceId: all-zero except in the create’s answer.

createdByUUID

The user who created it. Absent when no person did (the partner’s, a machine’s, rows from before creators were recorded).

createdAttime

updatedAttime

accountstring

Who or what the credential is, never a secret: the Google address a test names, user@host (with port and database) from a typed credential’s non-secret fields, a SeaTable base’s name and server. Shown to every reader. Absent until known.

createdByNamestring

The creator’s name (else their address), only while they are a member of the organization.

createdByMemberboolean

False once the creator is no longer a member of the organization. Absent with createdBy.

lastErrorobject

The last failure that still stands. Written by a failed test, a refused refresh (expired), and a run’s or poll’s definite refusal; a run’s 403 is kept as news (cause: forbidden) without changing status. Cleared by a working test, a sign-in, a config change, and the next run or poll that uses the connection and works.

attime

sourcestring

One of test, run, trigger, refresh, signin.

causestring

refused — the service refused the credential (401, SMTP 535, Postgres 28P01, MySQL 1045, …); expired — a refresh was refused for good; server — the server could not be reached; forbidden — a 403, news only; other.

One of refused, expired, server, forbidden, other.

messagestring

The service’s own words, masked of the step’s secrets, at most 1,000 characters.

runIdUUID

workflowIdUUID

workflowNamestring

While the workflow exists.

lastUseobject

The newest use the audit trail records (its connection.decrypt rows). Absent when the trail has none.

attime

kindstring

One of run, trigger, test, editor, signin.

runIdUUID

workflowIdUUID

workflowNamestring

byNamestring

The person, for a test, the builder or a sign-in, while a member of the organization.

oauthClientstring

For a connection that signs in: managed — the installation’s app; byo — its own client id; pasted — an access token with no refresh token, which cannot renew itself.

One of managed, byo, pasted.

lastSignInAttime

When a sign-in last stored tokens.

expiresAttime

When the connection stops working with no way to renew: tokenExpiresAt of a connection that is not refreshable. Absent for a refreshable one and when unknown.

testobject

Only on the answer of a create or a change sent with test: true: the test that let it be saved.

successboolean

Always true here: a refused test saves nothing and is a 422.

messagestring

The app’s own words.

unverifiedboolean

Present and true when the app cannot be tested without running a real step: saved, and nothing was proven.