get_connector_installation

Read a project's live installation of one connector — its state, health and the platform's own account for it — and learn why it is missing when it is.

Purpose

Reads the project's live installation of one connector: the state (pending, connected, degraded, revoked, disconnected) with its reason and detail, whether the creator can fix it (creator_actionable), whether it can act right now (operational), the platform's own external_id, display_name, handle and avatar_url, and the timestamps of its life. The REST twin is GET /v1/projects/{project}/connectors/{key}/installation.

Required ability

project-connector:view

Input schema

{
  "type": "object",
  "required": ["project_id", "connector"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "UUID of the project."
    },
    "connector": {
      "type": "string",
      "description": "The connector key, as list_connectors returns it."
    }
  }
}

Output shape

{
  "data": {
    "id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
    "connector": "telegram",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "scope": "project",
    "role": "live",
    "state": "degraded",
    "state_reason": "connector_api_unauthorized",
    "state_detail": "The token was revoked in @BotFather.",
    "creator_actionable": true,
    "operational": true,
    "external_id": "7123456789",
    "display_name": "Research Bot",
    "handle": "research_bot",
    "avatar_url": null,
    "health_checked_at": "2026-09-12T06:00:00Z",
    "connected_at": "2026-04-21T09:15:00Z",
    "verified_at": "2026-09-11T06:00:00Z",
    "revoked_at": null,
    "disconnected_at": null,
    "uninstalled_at": null,
    "created_at": "2026-04-21T09:15:00Z"
  },
  "meta": {}
}

Example prompts

"Is the Telegram bot on Research Premium still connected?"

"Why is the Discord installation on my project degraded?"

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-connector:view.
RESOURCE_NOT_FOUND — the project is not visible to this token; or context.reason is unknown_connector (the key names no connector) or not_installed (the project has no live installation of it).

list_connector_installations — every installation, standbys included.
get_connector — what the connector can do.
Connectors API