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/
| Parameter | Default | Description |
|---|---|---|
api_key | env GETSOCIALAPI_API_KEY | your API key from the dashboard |
base_url | API endpoint | override only for testing |
timeout | 30 | per-request timeout, seconds |
max_retries | 3 | retries 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
| Exception | HTTP | Notes |
|---|---|---|
GetSocialAPIError | — | base class; also network errors |
APIKeyError | 401 | invalid or missing key |
BadRequestError | 400 | .field points to the bad parameter |
NotFoundError | 404 | object does not exist — never retried |
RateLimitError | 429 | .retry_after seconds |
ServiceUnavailableError | 503 | no live accounts, .retry_after |
InstagramError | any | upstream 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