# Get a Connect Session

> Read the status and outcome of a connect link

- **URL**: https://orshot.com/docs/api-reference/social-connect-session-get

---

Read a connect session created with [Create a Connect Link](https://orshot.com/docs/api-reference/social-connect-session-create). Poll it after the person comes back to your `return_url`, or on a schedule while the link is live. A session stays readable for 24 hours after it was created.

The response never repeats `connect_url`.

Same access as [Create a Connect Link](https://orshot.com/docs/api-reference/social-connect-session-create):
enabled per workspace on the Enterprise plan, for the workspace's API keys and
first party clients like the [Orshot MCP server](https://orshot.com/agents).
Third-party OAuth apps are refused.

## Endpoint

### GET /social/connect-sessions/:id

```markdown tab="Endpoint"
https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA
```

## Request Example

```js
await fetch(
  "https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer <ORSHOT_API_KEY>",
    },
  },
);
```

## Response Example

```json
{
  "data": {
    "id": "cs_9kq2N0xYv3b8ZtQ1mL7wPA",
    "object": "social_connect_session",
    "status": "connected",
    "platform": "instagram",
    "external_id": "office_142",
    "post_id": null,
    "reconnect_account_id": null,
    "return_url": "https://crm.example.com/socials/done",
    "created_at": "2026-11-02T10:00:00.000Z",
    "expires_at": "2026-11-02T10:05:00.000Z",
    "opened_at": "2026-11-02T10:01:12.000Z",
    "completed_at": "2026-11-02T10:02:40.000Z",
    "account": {
      "id": 2291,
      "platform": "instagram",
      "username": "acme_athens",
      "name": "Acme Athens",
      "avatar_url": "https://…/avatar.jpg",
      "connected_at": "2026-11-02T10:02:40.000Z",
      "external_id": "office_142",
      "reconnected": false
    },
    "attached_posts": 2,
    "error": null
  }
}
```

## Response Fields

| Field            | Type    | Description |
| ---------------- | ------- | ----------- |
| `status`         | String  | `pending`, `opened`, `selecting`, `connected`, `failed`, `cancelled` or `expired` |
| `account`        | Object  | The connected account once `status` is `connected`. `account.id` is what you pass to the publish endpoints |
| `attached_posts` | Integer | Waiting posts for this platform that were attached to the new account |
| `error`          | Object  | `{ code, message }` once `status` is `failed` or `cancelled`, otherwise `null` |

## Failure Codes

| `error.code`                    | Meaning |
| ------------------------------- | ------- |
| `platform_denied`               | The person cancelled the platform login |
| `account_mismatch`              | A different account was signed in than the one the link was made for |
| `account_already_connected`     | That account is already connected to this workspace |
| `account_not_resolved`          | The platform did not hand back a usable account |
| `account_not_found`             | The account a reconnect link named no longer exists |
| `browser_mismatch`              | The platform returned to a browser other than the one that pressed Continue (a forwarded platform page). Nothing is stored |
| `social_requires_paid_account`  | The workspace's plan stopped including social accounts between creating the link and the login |
| `shopify_billed`                | Social accounts are not available on Shopify-billed plans yet |
| `selection_expired`             | The login or the identity choice took too long |
| `provider_error`                | Something else went wrong. Create a new link |
| `cancelled`                     | Cancelled through the API |

## Error Responses

| Code | `code`                | Description |
| ---- | --------------------- | ----------- |
| 403  | `enterprise_required` | Connect links are not enabled for this workspace's plan |
| 403  | `first_party_only`    | The caller is a third-party OAuth app |
| 404  | `session_not_found`   | Unknown id, a session of another workspace, or older than 24 hours |