Get a Connect Session
Read the status and outcome of a connect link
Published
GET
/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPAcurl -X GET "https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA" \
-H "Authorization: Bearer <ORSHOT_API_KEY>"const res = await fetch("https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA", {
method: "GET",
headers: {
Authorization: "Bearer <ORSHOT_API_KEY>",
},
});
const data = await res.json();import requests
response = requests.get(
"https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA",
headers={"Authorization": "Bearer <ORSHOT_API_KEY>"},
)
data = response.json()$ch = curl_init("https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer <ORSHOT_API_KEY>",
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);require "net/http"
require "json"
uri = URI("https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer <ORSHOT_API_KEY>"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)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.
Enterprise Only
Same access as Create a Connect Link: enabled per workspace on the Enterprise plan, for the workspace's API keys and first party clients like the Orshot MCP server. Third-party OAuth apps are refused.
Endpoint#
GET /social/connect-sessions/:id#
https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPARequest Example#
await fetch(
"https://api.orshot.com/v1/social/connect-sessions/cs_9kq2N0xYv3b8ZtQ1mL7wPA",
{
method: "GET",
headers: {
Authorization: "Bearer <ORSHOT_API_KEY>",
},
},
);Response Example#
{
"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 |
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