Skip to content

List Social Accounts API

The List Social Accounts API returns a paginated list of social accounts connected to your project. Use it to discover which accounts are available, filter them by platform or profile, search by handle or identity, and collect the integration id you will pass as accountId when creating posts. This page covers the endpoint contract, every query parameter, the response fields, pagination, and the status codes to handle.

Endpoint contract: GET {{API_BASE_URL}}/v1/connect/integrations

Call GET {{API_BASE_URL}}/v1/connect/integrations to retrieve connected social accounts for your project. The endpoint returns a paginated list, so a single call may contain only the first page of a larger result set. Plan to walk the full set by incrementing offset by limit until you have fetched total items, as described in the pagination section below. See the Endpoint contract example for the exact method and path, and the Query parameters table for the complete input contract.

Query parameters and filtering and search behavior

Choose filters based on the lookup task. Use platform when you only want accounts on one network, such as twitter, instagram, youtube, tiktok, pinterest, linkedin, bluesky, facebook, or threads. Use profileId when you need only the integrations bound to a specific profile; pass the literal string null to filter to integrations with no profile. Use q for a case-insensitive search across account identity fields, or to look up an exact integration ID. Use limit and offset to control page size and position, and sort to order results by createdAt in ascending or descending order. The Query parameters table lists each parameter with its type, default, and description, including the limit range of 1 to 100 and the sort default of desc.

Worked request examples

Start with a narrow request, for example filtering by platform and setting limit to 10, then inspect the returned integrations before widening the query. Confirm that each item carries the fields you need for the next step, especially id, platform, and createdAt. If the result looks incomplete, check total against the number of items returned and continue with the next page rather than assuming the first page is the whole set. The worked request examples show the exact endpoint, the x-access-key header, and platform and limit query values.

Response structure and pagination walk

A successful response contains success, total, and an integrations array. The total field is the number of integrations matching the filter across all pages, not just the current page. To walk the full result set, request the first page with offset 0, then increment offset by limit on each subsequent request until you have fetched total items. For example, with total 42 and limit 10, you would request offsets 0, 10, 20, 30, and 40, expecting the final page to contain the remaining items. Keep the sort value consistent across pages so items do not shift between requests. The Example response shows the structure with two integrations, including one with a null profileId and one bound to a profile.

Response field map

Each integration in the integrations array has an id, platform, platformUserId, displayName, imageUrl, profileId, and createdAt. Treat id as the key identifier: it is the integration ID you use as accountId when creating posts. platformUserId is the user or account ID on the platform and may be null, as may displayName, imageUrl, and profileId. createdAt is an ISO 8601 connection timestamp and is also the sort key. The Response fields table gives the type and nullability of every field so you can validate items before storing or displaying them.

Status codes and failure handling

Handle 200 as success and validate the response body before using the integrations. Treat 400 as invalid query parameters: check limit is between 1 and 100, sort is asc or desc, and platform, profileId, and q values are spelled as expected, then retry with corrected parameters. Do not treat an empty integrations array on a 200 response as an error; it can mean no accounts match the current filters, so broaden platform, profileId, or q and try again. The Status codes table summarizes the failure matrix for this endpoint.

Choosing filters for a given lookup task

Use this endpoint as the discovery step before posting: list social accounts, filter social accounts by platform when you need a specific network, paginate social accounts API results with limit and offset, and search social accounts by handle with q. Once you have the right integration, keep its id for use as accountId in post creation. If an account is missing, connect it first, and if it belongs to the wrong profile, move it between profiles without reconnecting. The related guides for connecting and moving accounts cover those next steps.

Query parameters
ParameterTypeDefaultDescription
platformstring—Filter by platform (e.g. twitter, instagram, youtube, tiktok, pinterest, linkedin, bluesky, facebook, threads)
profileIdstring—Filter to integrations bound to this profile. Pass null (literal string) to filter to integrations with no profile.
qstring—Case-insensitive search across account identity fields, or an exact integration ID
limitinteger20Page size (1–100)
offsetinteger0Number of integrations to skip
sortstring"desc"Sort by createdAt: "asc" or "desc"

Exact source contract; origin modularized as {{API_BASE_URL}}.

Response fields
FieldTypeDescription
idstringIntegration ID — use this as accountId when creating posts
platformstringPlatform name
platformUserIdstring | nullThe user/account ID on the platform
displayNamestring | nullDisplay name or handle
imageUrlstring | nullProfile image URL
profileIdstring | nullProfile this integration belongs to, if any
createdAtstringISO 8601 connection timestamp

Exact source contract.

Status codes
CodeMeaning
200Success
400Invalid query parameters

Exact source contract.

Endpoint contract
GET {{API_BASE_URL}}/v1/connect/integrations
List Twitter accounts with cURL
curl "{{API_BASE_URL}}/v1/connect/integrations?platform=twitter&limit=10" \
  -H "x-access-key: YOUR_API_KEY"
Example response
{
	"success": true,
	"total": 42,
	"integrations": [
		{
			"id": "abc123",
			"platform": "twitter",
			"platformUserId": "123456789",
			"displayName": "@yourhandle",
			"imageUrl": "https://pbs.twimg.com/profile_images/.../photo.jpg",
			"profileId": null,
			"createdAt": "2026-03-28T10:00:00.000Z"
		},
		{
			"id": "def456",
			"platform": "youtube",
			"platformUserId": "UCxxxxxxxx",
			"displayName": "My Channel",
			"imageUrl": "https://yt3.ggpht.com/.../photo.jpg",
			"profileId": "profile_acme",
			"createdAt": "2026-03-28T10:05:00.000Z"
		}
	]
}