Skip to content

Get Instagram follower count API

The Get Instagram follower count API returns the live Instagram follower count for a connected Instagram professional account. Use it when you need the current count at the moment of the call, identified by the required accountId query parameter and authorized with the x-access-key header. The endpoint is GET /v1/analytics/instagram/follower-stats. It returns a live count only: historical growth is not included, and historical growth requires daily snapshots. Each successful call costs 1 credit.

Endpoint summary and scope

This endpoint returns the connected Instagram professional account's live follower count. It does not return historical growth. If you need to measure growth over time, you must collect the live count repeatedly and build your own series from daily snapshots; no snapshot or growth data is included in this response. Each successful call costs 1 credit, so plan polling frequency accordingly and check the response before treating a count as available.

Authorization

Send the access key in the x-access-key header. The header name is x-access-key and its value is the token. This is separate from the accountId query parameter: the header authorizes the request, while accountId identifies which connected Instagram account to read. If the header is missing or invalid, do not expect a 200 response; handle the documented non-200 responses using the shared success and message shape described below.

Query parameters

The only documented query parameter is accountId. It is required, its type is string, and it is the integration ID for the connected Instagram account. Always include accountId in the query string, for example ?accountId=string as a placeholder for your integration ID. Do not move accountId into the body, because this GET request defines it as a query parameter. Verify the value against the connected account before calling, and treat a missing accountId as a failed request rather than retrying with a guessed value.

Response body and field map

On success, the response body contains success, accountId, platform, currentFollowers, and fetchedAt. The success field is boolean and is true in the documented 200 example. The accountId field echoes the integration ID as a string. The platform field is the string instagram. The currentFollowers field is the live follower count and may be an integer or null; null means the value is not made available, so your code must handle null explicitly instead of assuming a number. The fetchedAt field is a string in date-time format indicating when the count was fetched. See the field map and the example 200 response below for the exact types and requiredness.

Status codes and failure matrix

The documented status codes are 200, 400, 402, 403, 404, and 502. Only 200 returns the follower-count fields. The other documented codes return the shared shape with success and message. Do not invent a specific cause for any non-200 code from this page alone; instead, branch on the status code, read message, and surface it to the caller. In particular, distinguish a 200 with currentFollowers set to null from an error response: null is a successful response where the count is unavailable, while a non-200 response uses the message shape. See the failure matrix below for the exact mapping.

Origin-modular request example

To make the call, send a GET request to {{API_BASE_URL}}/v1/analytics/instagram/follower-stats with the required accountId query parameter and the x-access-key header. Replace the placeholder accountId value with the integration ID for the connected Instagram professional account and replace the token placeholder with your access key. After the call, check the status code first, then parse the body: on 200 read currentFollowers and fetchedAt, handling null for currentFollowers; on 400, 402, 403, 404, or 502 read message. See the request example and response examples below.

Input contract
FieldLocationTypeRequiredDescription
x-access-keyHeaderstring (<token>)Required for authorizationAccess key sent as the x-access-key header value.
accountIdQuery parameterstringRequiredIntegration ID for the connected Instagram account.

Exact documented input contract; no additional parameters documented.

200 response field map
FieldTypeRequiredNotes
successbooleanRequiredtrue in the documented 200 example.
accountIdstringRequiredIntegration ID for the connected Instagram account.
platformstringRequiredValue: "instagram".
currentFollowersinteger | nullRequiredLive follower count. null when Meta does not make the value available.
fetchedAtstringRequiredDate-time format.

Exact documented 200 response contract.

Status codes and failure matrix
Status codeContent typeResponse shapeFields
200application/jsonFollower-count objectsuccess (boolean), accountId (string), platform (string, "instagram"), currentFollowers (integer | null), fetchedAt (string, date-time)
400application/jsonShared error shapesuccess (boolean), message (string)
402application/jsonShared error shapesuccess (boolean), message (string)
403application/jsonShared error shapesuccess (boolean), message (string)
404application/jsonShared error shapesuccess (boolean), message (string)
502application/jsonShared error shapesuccess (boolean), message (string)

Exact documented status-to-shape mapping; specific error causes are not described in the source and are not invented here.

Request example: Get Instagram follower count
curl -X GET "{{API_BASE_URL}}/v1/analytics/instagram/follower-stats?accountId=string" \
  -H "x-access-key: <token>"
Example 200 response
{
  "success": true,
  "accountId": "string",
  "platform": "instagram",
  "currentFollowers": 0,
  "fetchedAt": "2019-08-24T14:15:22Z"
}
Example error response for 400, 402, 403, 404 and 502
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
accountId#1accountIdstring__0YesIntegration ID for the connected Instagram account.
response#2responseobject__0
response#2response.successboolean__1Yeskind: schemaValueIn; value: true
response#2response.accountIdstring__2Yes
response#2response.platformstring__3Yeskind: ; value: "instagram"
response#2response.currentFollowersinteger | null__4YesLive follower count. null when Meta does not make the value available.
response#2response.currentFollowers[variant1]integer__4_type:integerLive follower count. null when Meta does not make the value available.
response#2response.currentFollowers[variant2]null__4_type:nullLive follower count. null when Meta does not make the value available.
response#2response.fetchedAtstring__5Yeskind: ; value: date-time
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes