List Integrations API
The List Integrations API lists integrations connected to a project through GET /v1/connect/integrations. Use it to discover connected accounts, filter by platform or profile, search by account details, paginate results, and inspect authStatus, insightsReadable, and createdAt for each integration before using an integration in later calls.
Endpoint overview: GET /v1/connect/integrations
The List Integrations API returns integrations connected to a project. Call GET /v1/connect/integrations to list them. The worked request example uses {{API_BASE_URL}} before the unchanged path /v1/connect/integrations. Use the response id as the account identifier when creating posts, and use createdAt to understand connection order when sorting by connection date.
Authorization
Authorization uses the accessKey header x-access-key with a <token> value. Send x-access-key in the request header for every call to GET /v1/connect/integrations.
Query Parameters
All query parameters are optional. Use platform to limit results to one platform value. Use profileId to filter to integrations belonging to a profile, passing the literal string "null" to filter to integrations with no profile. Use q for case-insensitive search across displayName, username, and platform user ID, with a complete integration ID also matched exactly. Use limit and offset to paginate, sortBy to choose the sort field, and sort to choose ascending or descending order. See the Query Parameters table for types, defaults, ranges, and enums, and the Filter Decision Guide table for when to use each parameter.
Response Body
A successful call returns 200 application/json with success, total, and integrations. total is the total matched integrations across all pages. Each item in integrations includes id, platform, platformUserId, username, displayName, profileUrl, imageUrl, platformMetadata, profileId, profileName, appId, app, byok, authStatus, authFailureReason, insightsReadable, and createdAt. See the Response Fields table for requiredness and types. Check authStatus and authFailureReason to decide whether an integration can authenticate or needs reconnection, check insightsReadable to decide whether analytics can be read, and check byok and app to understand whether the integration was connected under a customer's own OAuth app.
200 application/json
The 200 application/json example shows the exact response shape with success set to true, total, and an integrations array containing one integration object. Preserve the field names and nullability shown in the Response Fields table when parsing the body. In particular, platformUserId, username, displayName, profileUrl, imageUrl, profileId, profileName, appId, and app can be null where the contract allows it, while id, platform, byok, authStatus, authFailureReason, insightsReadable, and createdAt are required fields on each integration.
| Parameter | Required | Type | Default / Range / Enum | Description |
|---|---|---|---|---|
| platform | Optional | string | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | Filter results to one platform. |
| profileId | Optional | string | Pass "null" (literal string) for no profile | Filter to integrations belonging to this profile. Pass "null" (literal string) to filter to integrations with no profile. |
| q | Optional | string | Case-insensitive search | Case-insensitive search across the connected account name (displayName), username, and platform user ID. A complete integration ID is also matched exactly. |
| limit | Optional | integer | Default 20; 1 <= value <= 100 | Page size (max 100) |
| offset | Optional | integer | Default 0; 0 <= value | Number of integrations to skip |
| sortBy | Optional | string | Default "createdAt" | Sort by connection date or account name (username, then displayName, then platform user ID). |
| sort | Optional | string | "asc" | "desc" | Sort direction. |
All query parameters are optional; preserve exact types, defaults, ranges and enums from the captured contract.
| Field | Required | Type | Description |
|---|---|---|---|
| success | Required | boolean | Whether the request succeeded. |
| total | Required | integer | Total matched integrations across all pages; 0 <= value. |
| integrations | Required | array<object> | List of integration objects for the current page. |
| integrations[].id | Required | string | Use this as accountId when creating posts. |
| integrations[].platform | Required | string | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" |
| integrations[].platformUserId | Required | string | null | The user ID on the platform, or null if not yet retrieved. |
| integrations[].username | Required | string | null | The public username or handle, including @ for handle-based platforms. |
| integrations[].displayName | Required | string | null | Human-readable display name of the connected account. |
| integrations[].profileUrl | Required | string | null (uri) | Public profile/page URL for the connected account, when it can be derived. |
| integrations[].imageUrl | Required | string | null (uri) | Profile image URL for the connected account, or null if unavailable. |
| integrations[].platformMetadata | Optional | object | Provider-specific public metadata for this connected account. |
| integrations[].profileId | Required | string | null | Profile this integration belongs to, or null if it was connected without a profile. |
| integrations[].profileName | Optional | string | null | Name of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list. |
| integrations[].appId | Required | string | null | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the system app was used. |
| integrations[].app | Required | object | null | The OAuth app metadata for BYOK integrations, or null when the system app was used. Object fields: id (string, optional), name (string, optional), imageUrl (string | null, optional). |
| integrations[].byok | Required | boolean | True when this integration was connected under the customer's own OAuth app (Bring Your Own Keys), i.e. appId is set. False when the system app is used. |
| integrations[].authStatus | Required | string | Whether this integration can authenticate or needs OAuth reconnection: "active" | "reconnect_required" |
| integrations[].authFailureReason | Required | string | null | Stable reason reconnection is required, or null while active: "token_expired" | "access_revoked" | "security_invalidation" | "refresh_rejected" | null |
| integrations[].insightsReadable | Required | boolean | null | Whether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false. |
| integrations[].createdAt | Required | string (date-time) | Connection date. |
Response is 200 application/json; requiredness and types preserved exactly from the captured contract.
| Field | Value | Meaning |
|---|---|---|
| authStatus | active | Integration can authenticate. |
| authStatus | reconnect_required | Integration needs OAuth reconnection. |
| authFailureReason | token_expired | Stable reason value for reconnection. |
| authFailureReason | access_revoked | Stable reason value for reconnection. |
| authFailureReason | security_invalidation | Stable reason value for reconnection. |
| authFailureReason | refresh_rejected | Stable reason value for reconnection. |
| authFailureReason | null | No failure reason, or null while active. |
authStatus and authFailureReason enums listed independently as captured; no pairing asserted.
| Parameter | Use it when | Decision criteria |
|---|---|---|
| platform | You only want accounts from one social platform. | Set platform to one of the enum values; omit it to list all platforms. |
| profileId | You want integrations for one profile, or integrations with no profile. | Set profileId to the profile ID, or to the literal string "null" for no profile. |
| q | You need to find an account by name, username, platform user ID, or exact integration ID. | Set q to the search text; matching is case-insensitive across displayName, username, and platform user ID, and a complete integration ID is matched exactly. |
| sortBy | You want a specific ordering field. | Sort by connection date or account name (username, then displayName, then platform user ID); default is "createdAt". |
| sort | You want ascending or descending order. | Set sort to "asc" or "desc". |
| limit | You want to control page size. | Set limit between 1 and 100; default is 20. |
| offset | You want to skip earlier results to reach a later page. | Set offset to the number of integrations to skip; default is 0. Use total to know when to stop paging. |
Decision criteria derived from the captured parameter descriptions; no new contract rules introduced.
Frequently asked questions
How do I authorize a List Integrations API request?
Send the x-access-key header with your token value. The endpoint is GET /v1/connect/integrations and returns a 200 application/json body with success, total, and integrations.
How do I paginate the integrations list?
Use limit for page size, from 1 to 100 with a default of 20, and offset for the number of integrations to skip, with a default of 0. Use total in the response to know how many integrations matched across all pages.
What does authStatus tell me about an integration?
Check authStatus. active means the integration can authenticate. reconnect_required means OAuth reconnection is needed, and authFailureReason is a separate field that can be token_expired, access_revoked, security_invalidation, refresh_rejected, or null while active.
How do I filter integrations with no profile?
Pass the literal string "null" as profileId to filter to integrations with no profile. Pass an actual profile ID to filter to integrations belonging to that profile.
What are the possible insightsReadable values?
insightsReadable can be true, false, or null. null means not determined yet, true means readable, and false means the account did not grant the insights permission even though auth can still be active.
curl -X GET "{{API_BASE_URL}}/v1/connect/integrations" -H "x-access-key: <token>"{
"success": true,
"total": 0,
"integrations": [
{
"id": "string",
"platform": "twitter",
"platformUserId": "string",
"username": "string",
"displayName": "string",
"profileUrl": "http://example.com",
"imageUrl": "http://example.com",
"platformMetadata": {},
"profileId": "string",
"profileName": "string",
"appId": "string",
"app": {
"id": "string",
"name": "string",
"imageUrl": "string"
},
"byok": true,
"authStatus": "active",
"authFailureReason": "token_expired",
"insightsReadable": true,
"createdAt": "2019-08-24T14:15:22Z"
}
]
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| platform#1 | platform | string | __0 | No | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| profileId#2 | profileId | string | __0 | No | Filter to integrations belonging to this profile. Pass "null" (literal string) to filter to integrations with no profile. | |
| q#3 | q | string | __0 | No | Case-insensitive search across the connected account name (displayName), username, and platform user ID. A complete integration ID is also matched exactly. | |
| limit#4 | limit | integer | __0 | No | Page size (max 100) | kind: schemaDefault; value: 20 | kind: schemaRange; value: 1 <= value <= 100 |
| offset#5 | offset | integer | __0 | No | Number of integrations to skip | kind: schemaDefault; value: 0 | kind: schemaRange; value: 0 <= value |
| sortBy#6 | sortBy | string | __0 | No | Sort by connection date or account name (username, then displayName, then platform user ID). | kind: schemaDefault; value: "createdAt" |
| sortBy#6 | sortBy[variant1] | string | __0_extends:__1 | Sort by connection date or account name (username, then displayName, then platform user ID). | kind: schemaDefault; value: "createdAt" | kind: schemaValueIn; value: "createdAt" | |
| sortBy#6 | sortBy[variant2] | string | __0_extends:__2 | Sort by connection date or account name (username, then displayName, then platform user ID). | kind: ; value: "createdAt" | kind: ; value: "name" | |
| sort#7 | sort | string | __0 | No | kind: schemaValueIn; value: "asc" | "desc" | |
| response#8 | response | object | __0 | |||
| response#8 | response.success | boolean | __1 | Yes | ||
| response#8 | response.total | integer | __2 | Yes | Total matched integrations across all pages | kind: schemaRange; value: 0 <= value |
| response#8 | response.integrations | array<object> | __3 | Yes | ||
| response#8 | response.integrations[] | object | __4 | |||
| response#8 | response.integrations[].id | string | __5 | Yes | Use this as accountId when creating posts | |
| response#8 | response.integrations[].platform | string | __6 | Yes | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| response#8 | response.integrations[].platformUserId | string | null | __7 | Yes | The user ID on the platform, or null if not yet retrieved | |
| response#8 | response.integrations[].platformUserId[variant1] | string | __7_type:string | The user ID on the platform, or null if not yet retrieved | ||
| response#8 | response.integrations[].platformUserId[variant2] | null | __7_type:null | The user ID on the platform, or null if not yet retrieved | ||
| response#8 | response.integrations[].username | string | null | __8 | Yes | The public username or handle, including @ for handle-based platforms | |
| response#8 | response.integrations[].username[variant1] | string | __8_type:string | The public username or handle, including @ for handle-based platforms | ||
| response#8 | response.integrations[].username[variant2] | null | __8_type:null | The public username or handle, including @ for handle-based platforms | ||
| response#8 | response.integrations[].displayName | string | null | __9 | Yes | Human-readable display name of the connected account | |
| response#8 | response.integrations[].displayName[variant1] | string | __9_type:string | Human-readable display name of the connected account | ||
| response#8 | response.integrations[].displayName[variant2] | null | __9_type:null | Human-readable display name of the connected account | ||
| response#8 | response.integrations[].profileUrl | string | null | __10 | Yes | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri |
| response#8 | response.integrations[].profileUrl[variant1] | string | __10_type:string | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri | |
| response#8 | response.integrations[].profileUrl[variant2] | null | __10_type:null | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri | |
| response#8 | response.integrations[].imageUrl | string | null | __11 | Yes | Profile image URL for the connected account, or null if unavailable | kind: schemaFormat; value: uri |
| response#8 | response.integrations[].imageUrl[variant1] | string | __11_type:string | Profile image URL for the connected account, or null if unavailable | kind: schemaFormat; value: uri | |
| response#8 | response.integrations[].imageUrl[variant2] | null | __11_type:null | Profile image URL for the connected account, or null if unavailable | kind: schemaFormat; value: uri | |
| response#8 | response.integrations[].platformMetadata | object | __12 | No | Provider-specific public metadata for this connected account. | |
| response#8 | response.integrations[].platformMetadata.[key: string] | any | true | No | ||
| response#8 | response.integrations[].profileId | string | null | __13 | Yes | Profile this integration belongs to, or null if it was connected without a profile | |
| response#8 | response.integrations[].profileId[variant1] | string | __13_type:string | Profile this integration belongs to, or null if it was connected without a profile | ||
| response#8 | response.integrations[].profileId[variant2] | null | __13_type:null | Profile this integration belongs to, or null if it was connected without a profile | ||
| response#8 | response.integrations[].profileName | string | null | __14 | No | Name of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list. | |
| response#8 | response.integrations[].profileName[variant1] | string | __14_type:string | Name of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list. | ||
| response#8 | response.integrations[].profileName[variant2] | null | __14_type:null | Name of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list. | ||
| response#8 | response.integrations[].appId | string | null | __15 | Yes | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used. | |
| response#8 | response.integrations[].appId[variant1] | string | __15_type:string | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used. | ||
| response#8 | response.integrations[].appId[variant2] | null | __15_type:null | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used. | ||
| response#8 | response.integrations[].app | object | null | __16 | Yes | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | |
| response#8 | response.integrations[].app[variant1] | object | __16_type:object | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | ||
| response#8 | response.integrations[].app[variant1].id | string | __17 | No | ||
| response#8 | response.integrations[].app[variant1].name | string | __18 | No | ||
| response#8 | response.integrations[].app[variant1].imageUrl | string | null | __19 | No | ||
| response#8 | response.integrations[].app[variant1].imageUrl[variant1] | string | __19_type:string | |||
| response#8 | response.integrations[].app[variant1].imageUrl[variant2] | null | __19_type:null | |||
| response#8 | response.integrations[].app[variant2] | null | __16_type:null | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | ||
| response#8 | response.integrations[].byok | boolean | __20 | Yes | True when this integration was connected under the customer's own OAuth app (Bring Your Own Keys), i.e. appId is set. False when the service's system app is used. | |
| response#8 | response.integrations[].authStatus | string | __21 | Yes | Whether this integration can authenticate or needs OAuth reconnection | |
| response#8 | response.integrations[].authStatus[variant1] | string | __21_extends:__22 | Whether this integration can authenticate or needs OAuth reconnection | kind: ; value: "active" | |
| response#8 | response.integrations[].authStatus[variant2] | string | __21_extends:__23 | Whether this integration can authenticate or needs OAuth reconnection | kind: ; value: "reconnect_required" | |
| response#8 | response.integrations[].authFailureReason | string | null | __24 | Yes | Stable reason reconnection is required, or null while active | |
| response#8 | response.integrations[].authFailureReason[variant1] | string | __24_extends:__25 | Stable reason reconnection is required, or null while active | kind: ; value: "token_expired" | |
| response#8 | response.integrations[].authFailureReason[variant2] | string | __24_extends:__26 | Stable reason reconnection is required, or null while active | kind: ; value: "access_revoked" | |
| response#8 | response.integrations[].authFailureReason[variant3] | string | __24_extends:__27 | Stable reason reconnection is required, or null while active | kind: ; value: "security_invalidation" | |
| response#8 | response.integrations[].authFailureReason[variant4] | string | __24_extends:__28 | Stable reason reconnection is required, or null while active | kind: ; value: "refresh_rejected" | |
| response#8 | response.integrations[].authFailureReason[variant5] | null | __24_extends:__29 | Stable reason reconnection is required, or null while active | ||
| response#8 | response.integrations[].insightsReadable | boolean | null | __30 | Yes | Whether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false. | |
| response#8 | response.integrations[].insightsReadable[variant1] | boolean | __30_type:boolean | Whether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false. | ||
| response#8 | response.integrations[].insightsReadable[variant2] | null | __30_type:null | Whether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false. | ||
| response#8 | response.integrations[].createdAt | string | __31 | Yes | kind: ; value: date-time |