list_connector_installations

List every connector installation a project holds — live and standby — with its state, health and the platform's own account for it.

Purpose

Answer "which connectors does this project run, and are they healthy?". Every row the Connectors tab shows: the connector key, the scope (project, or platform for a shared presence Subscriby runs), the role (live for the one that acts, standby for the spare the Disaster Recovery Program keeps), the state (pending, connected, degraded, revoked, disconnected) with its state_reason and state_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 when it was connected, verified, revoked, disconnected or uninstalled. Credentials and settings never appear. The REST twin is GET /v1/projects/{project}/connectors.

Required ability

project-connector:view-any

Input schema

{
  "type": "object",
  "required": ["project_id"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "UUID of the project whose installations to list."
    }
  }
}

Output shape

{
  "data": [
    {
      "id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
      "connector": "telegram",
      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
      "scope": "project",
      "role": "live",
      "state": "connected",
      "state_reason": null,
      "state_detail": null,
      "creator_actionable": false,
      "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-12T06:00:00Z",
      "revoked_at": null,
      "disconnected_at": null,
      "uninstalled_at": null,
      "created_at": "2026-04-21T09:15:00Z"
    }
  ],
  "meta": { "total": 1 }
}

Rows come oldest first.

Example prompts

"Is anything wrong with the connectors on Research Premium?"

"Which of my projects still run a standby bot?"

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-connector:view-any.
RESOURCE_NOT_FOUND — the project is not visible to this token.

get_connector_installation — one installation by connector key.
list_connectors — what each connector can do.
get_recovery_readiness — whether a standby is kept for every project.
Connectors API