Read monitored LinkedIn follower history

GET/sites/{site_id}/linkedin/competitors/{competitor_id}/followers/historylinkedin:read

OVERVIEW

Requires linkedin:read and an explicit site grant. Stored reads only: no LinkedIn requests, scraping, refresh jobs, or credit charges. source=live and unknown/repeated query parameters are rejected. Site/company/business-unit boundaries apply regardless of browser login or OAuth state. Use limit/cursor and repeat filters. Ordering is creation time then ID descending; follower history uses recorded_at then ID. Growth is recomputed from the previous authorized LinkedIn count, including before the date filter; cached legacy deltas are ignored.

Request	`GET https://satelliteai.io/api/v1/sites/{site_id}/linkedin/competitors/{competitor_id}/followers/history`
Permission	`linkedin:read`
Response	A list (cursor or offset paginated): `data` is `array of LinkedInFollowerObservation`.
Operation ID	`listLinkedInCompetitorFollowerHistory`

More context and worked examples are in the developer guide.

REQUEST

Example request

cURL · Bash

curl --fail-with-body \
  'https://satelliteai.io/api/v1/sites/123/linkedin/competitors/456/followers/history' \
  -H "Authorization: Bearer $SATELLITE_API_KEY"

Replace the example IDs with values returned by the discovery endpoints. Example values are placeholders, not real records.

Parameters

Name	In	Type	Description
`site_id`required	path	integer	ID from GET /sites. min 1
`competitor_id`required	path	integer	Use post id for post_id, or the monitored profile's competitor_id (not its observation id) for competitor_id. These are Satellite numeric IDs, not LinkedIn URNs. min 1
`limit`	query	integer	Maximum rows per page. default 50 · min 1 · max 100
`cursor`	query	string	Opaque next_cursor from the prior response. Expires after 24 hours; bound to integration, permissions, sites and unchanged filters. Restart pagination if access changes. max length 4096
`start_date`	query	string (date)	Inclusive YYYY-MM-DD boundary for recorded_at, in UTC.
`end_date`	query	string (date)	Inclusive YYYY-MM-DD boundary for recorded_at, in UTC.

Unknown or repeated query parameters return 400.

RESPONSE

Data dictionary

Stored results. Lists can be empty; latest followers can be null with availability not_available. Saved follower total on a UTC date with provenance and estimated reconciliation intervals. Missing dates are omitted; no extrapolation. Not a daily-gains report.

[] marks an array element. nullable means the value can be null; treat it as unknown, not zero. always present means the key is always included in the object.

Fields in data
Field	Type	Description
`data[].id`	integeralways present	Satellite identifier for this record. min 1
`data[].site_id`	integeralways present	Satellite site ID (from GET /sites). min 1
`data[].org_urn`	stringnullablealways present	max length 4096
`data[].snapshot_date`	string (date)nullablealways present	Observation date, not a proven reporting period.
`data[].fetched_at`	string (date-time)nullablealways present	When Satellite fetched the data from its source (UTC, RFC 3339).
`data[].created_at`	string (date-time)nullablealways present	When Satellite created the record (UTC, RFC 3339).
`data[].updated_at`	string (date-time)nullablealways present	When Satellite last updated the record (UTC, RFC 3339).
`data[].followers_fetched_at`	string (date-time)nullablealways present
`data[].total_followers`	integernullablealways present
`data[].follower_total_source`	stringnullablealways present	observed: networkSizes response; legacy_snapshot: retained observation with unverified historical fallback; estimated: reconstruction. max length 64
`data[].followers_observed_at`	string (date-time)nullablealways present
`data[].follower_estimate_method`	stringnullablealways present	max length 64
`data[].follower_anchor_date`	string (date)nullablealways present
`data[].follower_net_change`	integernullablealways present	Estimated calendar-period reconciliation; timing and provider corrections can affect this value.
`data[].inferred_follower_losses`	integernullablealways present	Estimated calendar-period reconciliation; timing and provider corrections can affect this value.
`data[].follower_reconciliation_adjustment`	integernullablealways present	Estimated calendar-period reconciliation; timing and provider corrections can affect this value.
`data[].follower_interval_start`	string (date)nullablealways present
`data[].follower_interval_end`	string (date)nullablealways present
`data[].follower_interval_gains`	integernullablealways present	Estimated calendar-period reconciliation; timing and provider corrections can affect this value.
`data[].followers_estimated`	booleanalways present
`data[].losses_source`	stringnullablealways present	max length 64
`data[].timezone`	stringalways present	one of: UTC
`data[].truncated_fields`	array of stringalways present	Fields exceeding public text, URL, JSON, or array limits.

Response metadata

Fields in meta
Field	Type	Description
`meta.request_id`	string	Request identifier; also returned in X-Request-ID. Include it in support requests.
`meta.api_version`	string	API version that produced the response. one of: v1
`meta.limit`	integer	Maximum records per page applied to this request. min 1 · max 100
`meta.has_more`	boolean	True when another page is available.
`meta.next_cursor`	stringnullable	Opaque cursor for the next page; send as cursor. Null on the last page.
`meta.availability`	string	available when stored data exists; not_available when it does not. one of: available, not_available
`meta.billing`	object	Present for paid live SERP requests; replayed receipts describe the original debit, not an additional charge.
`meta.billing.operation`	stringalways present	one of: client_api_serp_refresh
`meta.billing.credits_charged`	integeralways present	min 0
`meta.billing.transaction_id`	integeralways present
`meta.billing.replayed`	booleanalways present
`meta.source`	stringalways present	one of: stored
`meta.org_urn`	stringnullable	max length 4096
`meta.metric_period`	string	one of: lifetime
`meta.observation_history`	boolean

ERRORS

Error responses

Errors return {"error": {"code", "message", "request_id"}}. See error handling for retry guidance.

HTTP	When
`400`	Invalid or repeated query parameter, filter, limit, or cursor.
`401`	Missing, invalid, expired, or revoked credential.
`403`	Required scope, active integration, or company API entitlement is unavailable.
`404`	The resource is missing or outside the granted company/site boundary.
`413`	The response or stored artifact exceeds the configured retrieval limit.
`429`	API request quota exceeded. Retry after the indicated interval.
`503`	A required storage, rate-limit, or artifact dependency is unavailable.