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.
| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| x-access-key | Header | string (<token>) | Required for authorization | Access key sent as the x-access-key header value. |
| accountId | Query parameter | string | Required | Integration ID for the connected Instagram account. |
Exact documented input contract; no additional parameters documented.
| Field | Type | Required | Notes |
|---|---|---|---|
| success | boolean | Required | true in the documented 200 example. |
| accountId | string | Required | Integration ID for the connected Instagram account. |
| platform | string | Required | Value: "instagram". |
| currentFollowers | integer | null | Required | Live follower count. null when Meta does not make the value available. |
| fetchedAt | string | Required | Date-time format. |
Exact documented 200 response contract.
| Status code | Content type | Response shape | Fields |
|---|---|---|---|
| 200 | application/json | Follower-count object | success (boolean), accountId (string), platform (string, "instagram"), currentFollowers (integer | null), fetchedAt (string, date-time) |
| 400 | application/json | Shared error shape | success (boolean), message (string) |
| 402 | application/json | Shared error shape | success (boolean), message (string) |
| 403 | application/json | Shared error shape | success (boolean), message (string) |
| 404 | application/json | Shared error shape | success (boolean), message (string) |
| 502 | application/json | Shared error shape | success (boolean), message (string) |
Exact documented status-to-shape mapping; specific error causes are not described in the source and are not invented here.
curl -X GET "{{API_BASE_URL}}/v1/analytics/instagram/follower-stats?accountId=string" \
-H "x-access-key: <token>"{
"success": true,
"accountId": "string",
"platform": "instagram",
"currentFollowers": 0,
"fetchedAt": "2019-08-24T14:15:22Z"
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| accountId#1 | accountId | string | __0 | Yes | Integration ID for the connected Instagram account. | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | kind: schemaValueIn; value: true | |
| response#2 | response.accountId | string | __2 | Yes | ||
| response#2 | response.platform | string | __3 | Yes | kind: ; value: "instagram" | |
| response#2 | response.currentFollowers | integer | null | __4 | Yes | Live follower count. null when Meta does not make the value available. | |
| response#2 | response.currentFollowers[variant1] | integer | __4_type:integer | Live follower count. null when Meta does not make the value available. | ||
| response#2 | response.currentFollowers[variant2] | null | __4_type:null | Live follower count. null when Meta does not make the value available. | ||
| response#2 | response.fetchedAt | string | __5 | Yes | kind: ; value: date-time | |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |