FetchPI
Log in

Guides

Instagram Data API Integration Guide: Profiles, Posts and Search Without Scrapers

Integrate Instagram profile, posts and search data as normalized JSON: endpoint map, pagination, freshness modes and error semantics for a maintenance-free integration.

Last reviewed

Quickstart

Every request needs one header: Authorization: Bearer $FETCHPI_API_KEY. Create a free key in the console and you can replay every snippet on this page as-is.

curl -s -H "Authorization: Bearer $FETCHPI_API_KEY"   "https://fetchpi.com/v1/ig/users/{username}?freshness=default"

The endpoint map

The ig. prefix maps to the Instagram platform at the resolver — the same five-capability shape every FetchPI platform shares.

  • GET /v1/ig/users/{username} — profile.
  • GET /v1/ig/users/{username}/posts — the post feed with engagement metrics.
  • GET /v1/ig/posts/{id} — one post (addressed by its platform id).
  • GET /v1/ig/posts/{id}/comments — comments.
  • GET /v1/ig/search/posts — keyword search.

Integration checklist

  • Auth: one bearer key for every platform — no per-platform tokens to rotate.
  • Pagination: read next_cursor, echo it back as cursor; null means exhausted.
  • Retries: 429 RATE_LIMITED and 502 UPSTREAM_ERROR are transient — back off and retry. 4xx contract errors are not.
  • Budget: set freshness=default and a max_age for anything that re-reads the same entities on a schedule.
  • Audit: log meta.request_id from every response — support and billing questions resolve against it.

Error semantics you should design for

Failures are never billed: an upstream outage releases the full hold and answers 502 UPSTREAM_ERROR with the attempt summary. An exhausted balance answers 403 INSUFFICIENT_CREDITS. A cache-mode miss (data older than your max_age is not in the cache) answers 404 DATA_NOT_FOUND — switch to default or live when you see it.