Get a Connect Session

Read the status and outcome of a connect link

Published

GET
/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA
curl -X GET "https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>"

Read a connect session created with Create a Connect Link. 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.

Endpoint#

GET /social/connect-sessions/:id#

Endpoint
https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA

Request Example#

JavaScript
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#

FieldTypeDescription
statusStringpending, opened, selecting, connected, failed, cancelled or expired
accountObjectThe connected account once status is connected. account.id is what you pass to the publish endpoints
attached_postsIntegerWaiting posts for this platform that were attached to the new account
errorObject{ code, message } once status is failed or cancelled, otherwise null

Failure Codes#

error.codeMeaning
platform_deniedThe person cancelled the platform login
account_mismatchA different account was signed in than the one the link was made for
account_already_connectedThat account is already connected to this workspace
account_not_resolvedThe platform did not hand back a usable account
account_not_foundThe account a reconnect link named no longer exists
browser_mismatchThe platform returned to a browser other than the one that pressed Continue (a forwarded platform page). Nothing is stored
social_requires_paid_accountThe workspace's plan stopped including social accounts between creating the link and the login
shopify_billedSocial accounts are not available on Shopify-billed plans yet
selection_expiredThe login or the identity choice took too long
provider_errorSomething else went wrong. Create a new link
cancelledCancelled through the API

Error Responses#

CodecodeDescription
403enterprise_requiredConnect links are not enabled for this workspace's plan
403first_party_onlyThe caller is a third-party OAuth app
404session_not_foundUnknown id, a session of another workspace, or older than 24 hours
Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 40+ integrations
  • White-label embed for your own app
  • 100 free credits a month, no credit card required