Skip to content

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.

Query Parameters
ParameterRequiredTypeDefault / Range / EnumDescription
platformOptionalstring"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"Filter results to one platform.
profileIdOptionalstringPass "null" (literal string) for no profileFilter to integrations belonging to this profile. Pass "null" (literal string) to filter to integrations with no profile.
qOptionalstringCase-insensitive searchCase-insensitive search across the connected account name (displayName), username, and platform user ID. A complete integration ID is also matched exactly.
limitOptionalintegerDefault 20; 1 <= value <= 100Page size (max 100)
offsetOptionalintegerDefault 0; 0 <= valueNumber of integrations to skip
sortByOptionalstringDefault "createdAt"Sort by connection date or account name (username, then displayName, then platform user ID).
sortOptionalstring"asc" | "desc"Sort direction.

All query parameters are optional; preserve exact types, defaults, ranges and enums from the captured contract.

Response Fields
FieldRequiredTypeDescription
successRequiredbooleanWhether the request succeeded.
totalRequiredintegerTotal matched integrations across all pages; 0 <= value.
integrationsRequiredarray<object>List of integration objects for the current page.
integrations[].idRequiredstringUse this as accountId when creating posts.
integrations[].platformRequiredstring"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
integrations[].platformUserIdRequiredstring | nullThe user ID on the platform, or null if not yet retrieved.
integrations[].usernameRequiredstring | nullThe public username or handle, including @ for handle-based platforms.
integrations[].displayNameRequiredstring | nullHuman-readable display name of the connected account.
integrations[].profileUrlRequiredstring | null (uri)Public profile/page URL for the connected account, when it can be derived.
integrations[].imageUrlRequiredstring | null (uri)Profile image URL for the connected account, or null if unavailable.
integrations[].platformMetadataOptionalobjectProvider-specific public metadata for this connected account.
integrations[].profileIdRequiredstring | nullProfile this integration belongs to, or null if it was connected without a profile.
integrations[].profileNameOptionalstring | nullName 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[].appIdRequiredstring | nullThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the system app was used.
integrations[].appRequiredobject | nullThe 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[].byokRequiredbooleanTrue 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[].authStatusRequiredstringWhether this integration can authenticate or needs OAuth reconnection: "active" | "reconnect_required"
integrations[].authFailureReasonRequiredstring | nullStable reason reconnection is required, or null while active: "token_expired" | "access_revoked" | "security_invalidation" | "refresh_rejected" | null
integrations[].insightsReadableRequiredboolean | nullWhether 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[].createdAtRequiredstring (date-time)Connection date.

Response is 200 application/json; requiredness and types preserved exactly from the captured contract.

Auth Status and Failure Reason Values
FieldValueMeaning
authStatusactiveIntegration can authenticate.
authStatusreconnect_requiredIntegration needs OAuth reconnection.
authFailureReasontoken_expiredStable reason value for reconnection.
authFailureReasonaccess_revokedStable reason value for reconnection.
authFailureReasonsecurity_invalidationStable reason value for reconnection.
authFailureReasonrefresh_rejectedStable reason value for reconnection.
authFailureReasonnullNo failure reason, or null while active.

authStatus and authFailureReason enums listed independently as captured; no pairing asserted.

Filter Decision Guide
ParameterUse it whenDecision criteria
platformYou only want accounts from one social platform.Set platform to one of the enum values; omit it to list all platforms.
profileIdYou 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.
qYou 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.
sortByYou want a specific ordering field.Sort by connection date or account name (username, then displayName, then platform user ID); default is "createdAt".
sortYou want ascending or descending order.Set sort to "asc" or "desc".
limitYou want to control page size.Set limit between 1 and 100; default is 20.
offsetYou 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.

List integrations request example
curl -X GET "{{API_BASE_URL}}/v1/connect/integrations" -H "x-access-key: <token>"
200 application/json response example
{
  "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"
    }
  ]
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
platform#1platformstring__0Nokind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
profileId#2profileIdstring__0NoFilter to integrations belonging to this profile. Pass "null" (literal string) to filter to integrations with no profile.
q#3qstring__0NoCase-insensitive search across the connected account name (displayName), username, and platform user ID. A complete integration ID is also matched exactly.
limit#4limitinteger__0NoPage size (max 100)kind: schemaDefault; value: 20 | kind: schemaRange; value: 1 <= value <= 100
offset#5offsetinteger__0NoNumber of integrations to skipkind: schemaDefault; value: 0 | kind: schemaRange; value: 0 <= value
sortBy#6sortBystring__0NoSort by connection date or account name (username, then displayName, then platform user ID).kind: schemaDefault; value: "createdAt"
sortBy#6sortBy[variant1]string__0_extends:__1Sort by connection date or account name (username, then displayName, then platform user ID).kind: schemaDefault; value: "createdAt" | kind: schemaValueIn; value: "createdAt"
sortBy#6sortBy[variant2]string__0_extends:__2Sort by connection date or account name (username, then displayName, then platform user ID).kind: ; value: "createdAt" | kind: ; value: "name"
sort#7sortstring__0Nokind: schemaValueIn; value: "asc" | "desc"
response#8responseobject__0
response#8response.successboolean__1Yes
response#8response.totalinteger__2YesTotal matched integrations across all pageskind: schemaRange; value: 0 <= value
response#8response.integrationsarray<object>__3Yes
response#8response.integrations[]object__4
response#8response.integrations[].idstring__5YesUse this as accountId when creating posts
response#8response.integrations[].platformstring__6Yeskind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
response#8response.integrations[].platformUserIdstring | null__7YesThe user ID on the platform, or null if not yet retrieved
response#8response.integrations[].platformUserId[variant1]string__7_type:stringThe user ID on the platform, or null if not yet retrieved
response#8response.integrations[].platformUserId[variant2]null__7_type:nullThe user ID on the platform, or null if not yet retrieved
response#8response.integrations[].usernamestring | null__8YesThe public username or handle, including @ for handle-based platforms
response#8response.integrations[].username[variant1]string__8_type:stringThe public username or handle, including @ for handle-based platforms
response#8response.integrations[].username[variant2]null__8_type:nullThe public username or handle, including @ for handle-based platforms
response#8response.integrations[].displayNamestring | null__9YesHuman-readable display name of the connected account
response#8response.integrations[].displayName[variant1]string__9_type:stringHuman-readable display name of the connected account
response#8response.integrations[].displayName[variant2]null__9_type:nullHuman-readable display name of the connected account
response#8response.integrations[].profileUrlstring | null__10YesPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#8response.integrations[].profileUrl[variant1]string__10_type:stringPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#8response.integrations[].profileUrl[variant2]null__10_type:nullPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#8response.integrations[].imageUrlstring | null__11YesProfile image URL for the connected account, or null if unavailablekind: schemaFormat; value: uri
response#8response.integrations[].imageUrl[variant1]string__11_type:stringProfile image URL for the connected account, or null if unavailablekind: schemaFormat; value: uri
response#8response.integrations[].imageUrl[variant2]null__11_type:nullProfile image URL for the connected account, or null if unavailablekind: schemaFormat; value: uri
response#8response.integrations[].platformMetadataobject__12NoProvider-specific public metadata for this connected account.
response#8response.integrations[].platformMetadata.[key: string]anytrueNo
response#8response.integrations[].profileIdstring | null__13YesProfile this integration belongs to, or null if it was connected without a profile
response#8response.integrations[].profileId[variant1]string__13_type:stringProfile this integration belongs to, or null if it was connected without a profile
response#8response.integrations[].profileId[variant2]null__13_type:nullProfile this integration belongs to, or null if it was connected without a profile
response#8response.integrations[].profileNamestring | null__14NoName 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#8response.integrations[].profileName[variant1]string__14_type:stringName 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#8response.integrations[].profileName[variant2]null__14_type:nullName 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#8response.integrations[].appIdstring | null__15YesThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#8response.integrations[].appId[variant1]string__15_type:stringThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#8response.integrations[].appId[variant2]null__15_type:nullThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#8response.integrations[].appobject | null__16YesThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#8response.integrations[].app[variant1]object__16_type:objectThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#8response.integrations[].app[variant1].idstring__17No
response#8response.integrations[].app[variant1].namestring__18No
response#8response.integrations[].app[variant1].imageUrlstring | null__19No
response#8response.integrations[].app[variant1].imageUrl[variant1]string__19_type:string
response#8response.integrations[].app[variant1].imageUrl[variant2]null__19_type:null
response#8response.integrations[].app[variant2]null__16_type:nullThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#8response.integrations[].byokboolean__20YesTrue 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#8response.integrations[].authStatusstring__21YesWhether this integration can authenticate or needs OAuth reconnection
response#8response.integrations[].authStatus[variant1]string__21_extends:__22Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "active"
response#8response.integrations[].authStatus[variant2]string__21_extends:__23Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "reconnect_required"
response#8response.integrations[].authFailureReasonstring | null__24YesStable reason reconnection is required, or null while active
response#8response.integrations[].authFailureReason[variant1]string__24_extends:__25Stable reason reconnection is required, or null while activekind: ; value: "token_expired"
response#8response.integrations[].authFailureReason[variant2]string__24_extends:__26Stable reason reconnection is required, or null while activekind: ; value: "access_revoked"
response#8response.integrations[].authFailureReason[variant3]string__24_extends:__27Stable reason reconnection is required, or null while activekind: ; value: "security_invalidation"
response#8response.integrations[].authFailureReason[variant4]string__24_extends:__28Stable reason reconnection is required, or null while activekind: ; value: "refresh_rejected"
response#8response.integrations[].authFailureReason[variant5]null__24_extends:__29Stable reason reconnection is required, or null while active
response#8response.integrations[].insightsReadableboolean | null__30YesWhether 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#8response.integrations[].insightsReadable[variant1]boolean__30_type:booleanWhether 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#8response.integrations[].insightsReadable[variant2]null__30_type:nullWhether 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#8response.integrations[].createdAtstring__31Yeskind: ; value: date-time