Skip to main content

Instagram SDK (Python)

The official Python client for the GetSocialAPI Instagram API. A thin layer over the REST API: auth, automatic retries and typed exceptions — you get raw Instagram JSON, one page per call.

Endpoint semantics — parameters, response fields, limits and notes — live in the API Reference. This page covers only the library itself.

Source code: github.com/GetSocialAPI/Instagram-Scraper-API

Installation​

pip install git+https://github.com/GetSocialAPI/Instagram-Scraper-API.git

Requires Python 3.9+ and requests.

Client​

from getsocialapi import Client

client = Client(api_key="gsa_live_...")
# Dashboard & keys: https://getsocialapi.com/
ParameterDefaultDescription
api_keyenv GETSOCIALAPI_API_KEYyour API key from the dashboard
base_urlAPI endpointoverride only for testing
timeout30per-request timeout, seconds
max_retries3retries on 429/503/5xx and network errors
client.health()
# {"ok": True, "state": "ready"}

All endpoints hang off client.instagram.* — see the Instagram API Reference for what is available and what each call returns.

Pagination​

Every method returns one raw page as received. Pass the cursor from the previous response (next_max_id as max_id for Instagram, page_info.end_cursor as after for Facebook) until it is null / has_next_page is false.

Errors​

from getsocialapi import NotFoundError, RateLimitError
import time

try:
client.instagram.user_info(25025320)
except NotFoundError:
... # object does not exist — do not retry
except RateLimitError as e:
time.sleep(e.retry_after) # seconds from Retry-After
ExceptionHTTPNotes
GetSocialAPIError—base class; also network errors
APIKeyError401invalid or missing key
BadRequestError400.field points to the bad parameter
NotFoundError404object does not exist — never retried
RateLimitError429.retry_after seconds
ServiceUnavailableError503no live accounts, .retry_after
InstagramErroranyupstream Instagram error, .status

Retries are automatic for 429/500/502/503/504 (up to max_retries), honoring Retry-After.

Validation​

Client-side checks raise ValueError before any network call:

  • count — integer 1–50
  • ids / pk — digits, up to 20 characters
  • username — 1–64 characters
  • tag — 1–64 characters (leading # trimmed)
  • keyword — 1–100 characters, spaces are URL-encoded automatically