Quickstart
- Create a free account. You get 100 free credits.
- On your dashboard, create an API key. It's shown only once, so copy it somewhere safe.
- Make your first call:
curl "https://socialgraph.dev/api/v1/instagram/profile?username=instagram" \ -H "Authorization: Bearer YOUR_API_KEY"
You'll get the public profile of @instagram as JSON, and 2 credits are used. Every endpoint page also has ready-to-paste code for PHP, Python, Node.js and Go.
Authentication
Send your API key with every request, in either header:
Authorization: Bearer socialgraph_your_key_here X-API-Key: socialgraph_your_key_here
Keys start with socialgraph_. You can create up to 10 keys and revoke any key instantly from your dashboard; a revoked key stops working immediately. Keep keys on your server, never in browser or mobile app code.
Requests
Base URL: https://socialgraph.dev/api/v1. All requests use HTTPS.
- All endpoints use GET with parameters in the query string, e.g.
?username=instagram. URL-encode values (every HTTP library does this for you). - List parameters repeat the name with
[]:?image_urls[]=https%3A%2F%2F…a.jpg&image_urls[]=https%3A%2F%2F…b.jpg. A single item can also be sent as?image_urls=https%3A%2F%2F…a.jpg. - Unknown parameters are ignored. Required parameters are listed on each endpoint's page.
Responses & headers
Successful calls return HTTP 200 with JSON. Useful response headers:
| Header | Meaning |
|---|---|
X-Credits-Used | Credits this call used |
X-Credits-Remaining | Your balance after this call |
X-Request-Id | Unique ID for the request; include it when contacting support |
Credits & billing
- Each endpoint has a fixed credit cost, shown on its page and on the pricing page.
- Only successful calls are charged. Errors, "not found" responses, invalid input and provider failures are free.
- When your balance is too low, calls return
402 insufficient_creditswith therequiredandavailablecredits. Nothing is charged. - Credits never expire. Top up any time from your billing page; new credits work immediately.
Errors
Errors return a JSON body with a machine-readable code and a human-readable message:
{"error": {"code": "insufficient_credits", "message": "Not enough credits to call this API.", "required": 2, "available": 0}}
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_idempotency_key | Idempotency-Key must be 1–128 printable ASCII characters, e.g. a UUID |
| 401 | unauthorized | Check the API key is correct and not revoked |
| 402 | insufficient_credits | Top up credits |
| 404 | not_found | The endpoint path doesn't exist |
| 404 | e.g. post not found | The account, post or video doesn't exist or isn't public |
| 405 | method_not_allowed | Use the method shown on the endpoint's page |
| 409 | duplicate_request | This Idempotency-Key was already used; send a new one for a new call |
| 422 | validation_error | Fix the parameters listed under missing and invalid |
| 429 | too_many_failed_attempts | Too many requests with invalid keys from your IP; wait a minute |
| 502 | upstream_unavailable, upstream_invalid_response | The data source had a temporary problem; retry shortly |
| 503 | service_unavailable | Temporary outage; retry with backoff |
None of these are charged.
Idempotency
Network problems can make it unclear whether a call went through. Send a unique Idempotency-Key header (up to 128 printable ASCII characters, e.g. a UUID) and retrying with the same key can never charge you twice: once a call with that key has been charged, repeating it returns 409 duplicate_request. If the call failed and wasn't charged (for example a provider error or 402), you can retry with the same key. Keys are remembered for 7 days.
Limits & timeouts
- No per-key rate limit. Your credit balance is the only limit, and you can run requests in parallel.
- Requests with invalid API keys are limited to 30 per minute per IP address.
- Text parameters up to 2,048 characters; lists up to 100 items (age & gender: up to 10 images per call).
- Some requests take time: comments and YouTube audience demographics can take 20–60 seconds, most others 3–15 seconds. Set your HTTP client timeout to at least 90 seconds.
Instagram field names
Every Instagram endpoint uses the same names for the same things, so you can share parsing code between endpoints.
| Field | Meaning |
|---|---|
id | Instagram ID of the account or post (always a string) |
short_code | The post code in its URL: instagram.com/p/<short_code> |
owner | The account that owns a post: {id, username} |
post_date, comment_date | ISO 8601 date-time in UTC, e.g. 2026-10-09T15:57:15Z |
followers, following, media_count | Account counts (integers) |
like_count, comment_count, view_count | Post counts (integers; view_count is null for photos) |
avatar, display_url, video_url | Media URLs (see below) |
product_type | clips (reel), carousel_container, or feed |
Data & media URLs
- Only publicly available data is returned. Private accounts and private content are not accessible.
- Data is fetched live from the platform when you call.
- Image and video URLs (
avatar,display_url,video_url) are signed by the platform's CDN and expire after a few days. Download the files if you need to keep them. - You're responsible for using the data in line with applicable laws and the platforms' terms. See our terms.
X-Request-Id of the call.