SignalShelf · Developer documentation

Instagram profile

Sample profile responses are available. Instagram live profile and media requests are disabled in production pending written source authorization and independent review.

Request

POST /api/v1/profiles · authenticate with the x-api-key header.

Parameter	Type	Required	Description
`platform`	string	Yes	"instagram"
`handle`	string	Yes	Username or https://www.instagram.com/<username>/ URL. Reel and story URLs are rejected.
`mode`	string	No	"live" for real data, "demo" for a free labeled sample. Default "demo".
`freshness`	string	No	Oldest cached result you accept: "1h", "24h" (default), "7d", or "live" to force a refresh.

REQUEST EXAMPLE

curl "$SIGNALSHELF_BASE_URL/api/v1/profiles" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SIGNALSHELF_API_KEY" \
  --data '{"platform":"instagram","handle":"ghar.ka.mali","mode":"demo","freshness":"24h"}'

const response = await fetch(`${process.env.SIGNALSHELF_BASE_URL}/api/v1/profiles`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.SIGNALSHELF_API_KEY },
  body: JSON.stringify({platform: "instagram", handle: "ghar.ka.mali", mode: "demo", freshness: "24h"}),
});
const { data, meta } = await response.json();

import os, requests

response = requests.post(
    f"{os.environ['SIGNALSHELF_BASE_URL']}/api/v1/profiles",
    headers={"x-api-key": os.environ["SIGNALSHELF_API_KEY"]},
    json={"platform":"instagram","handle":"ghar.ka.mali","mode":"demo","freshness":"24h"},
    timeout=30,
)
data = response.json()["data"]

Example response

Labeled sample fixture. Values are illustrative and do not describe a real creator.

EXAMPLE

{
  "data": {
    "platform": "instagram",
    "handle": "ghar.ka.mali",
    "name": "Sample creator",
    "bio": "Illustrative sample data for exploring SignalShelf. Not a real profile lookup.",
    "followers": 128400,
    "following": 842,
    "posts": 326,
    "verified": false,
    "url": "https://www.instagram.com/ghar.ka.mali/",
    "avatar": null,
    "sample": true,
    "provider": "sample-fixture",
    "details": {
      "user_pk": null,
      "is_private": false,
      "pronouns": [],
      "is_memorialized": false,
      "whatsapp": null,
      "linked_facebook_page": {},
      "latest_story_at": null,
      "category": null,
      "is_business": false,
      "is_professional": false,
      "business_email": null,
      "business_phone": null,
      "business_address": {},
      "highlights": 0,
      "engagement_rate": null,
      "related_accounts": [],
      "recent_posts": []
    }
  },
  "meta": {
    "event_id": "sample",
    "mode": "demo",
    "cache": "SAMPLE",
    "credits_charged": 0,
    "fetched_at": null,
    "age_seconds": null,
    "duration_ms": 0
  }
}

Profile fields

Every platform returns these fields. Fields a platform does not expose are null (or [] for links); they are never guessed.

Field	Type	Description
`platform`	string	Platform you requested.
`handle`	string	Normalized handle (lowercase, no @).
`name`	string	Display name.
`bio`	string	Profile description, as shown publicly.
`followers`	number	Follower or subscriber count.
`following`	number	Accounts this profile follows.
`posts`	number	Total posts, videos, pins or repositories, depending on platform.
`verified`	boolean	Platform verification badge, when exposed.
`url`	string	Canonical public profile URL.
`avatar`	string \| null	Profile picture URL (largest available).
`sample`	boolean	Always false for live data; true only in sample mode.
`provider`	string	Engine that produced the data.
`details`	object	Platform-specific fields, listed below.

Instagram-specific fields (details)

Returned inside data.details.

Field	Type	Description
`details.user_pk`	string \| null	Numeric user primary key.
`details.is_private`	boolean	Whether this account is private. Private posts and connection lists are never returned.
`details.pronouns`	array	Pronouns list.
`details.is_memorialized`	boolean	Memorialized account.
`details.whatsapp`	string \| null	WhatsApp link from the bio, when present.
`details.linked_facebook_page`	object	Linked Facebook page { id, name }.
`details.latest_story_at`	string \| null	Time of the most recent story (ISO 8601).
`details.category`	string \| null	Business category, when public.
`details.is_business`	boolean	Business account flag.
`details.is_professional`	boolean	Professional (creator or business) account. Full profile only.
`details.business_email`	string \| null	Public business email. Full profile only.
`details.business_phone`	string \| null	Public business phone. Full profile only.
`details.business_address`	object	Business address { street, city, zip, latitude, longitude }. Full profile only.
`details.highlights`	number	Story highlight count. Full profile only.
`details.engagement_rate`	string \| null	Average (likes + comments) per recent post / followers, in %. Full profile only.
`details.related_accounts`	array	Usernames Instagram suggests as related. Full profile only.
`details.recent_posts`	array	Latest 12 posts { shortcode, url, type, caption, taken_at, likes, comments, views, thumbnail }. Full profile only.

Response metadata

Field	Type	Description
`meta.cache`	string	HIT (served from cache, 0 credits), MISS (fresh fetch) or SAMPLE.
`meta.credits_charged`	number	Credits charged for this request.
`meta.fetched_at`	string	When the data was fetched from the source.
`meta.age_seconds`	number	Age of the data at response time.
`meta.duration_ms`	number	Server processing time.

Errors

Every failure is free: reserved credits are refunded automatically.

Field	Type	Description
`404 PROFILE_NOT_FOUND`	error	The profile does not exist publicly.
`422 PROFILE_UNAVAILABLE`	error	The source did not expose even the public profile fields for this account.
`503 SOURCE_NOT_AUTHORIZED`	error	Live access for this platform is disabled in production pending source authorization. No credits are charged.
`503 SOURCE_AUTH_REQUIRED`	error	The source demanded a login for this request. Retry later.
`503 UPSTREAM_RATE_LIMITED`	error	The source is rate limiting. Retry after the Retry-After header.
`402 INSUFFICIENT_CREDITS`	error	Not enough credits for a fresh lookup. Cached and sample results stay free.

Limitations

Instagram live profile and media requests are disabled in production pending written source authorization and independent review.

Instagram live profile and media requests are disabled in production until written source authorization and an independent review are complete.

Local parser tests and successful page reads do not grant permission to commercialize a source method.

Additional public fields depend on what Instagram returns to a logged-out request. extraction_method identifies the available public source path. Access denials, login walls, and rate limits stop without proxy or browser retries.

For private accounts, only public profile-header fields exposed by Instagram may be returned. Private posts, stories, and follower/following lists are never returned.

Explore the API in your workspace. Sample results and accepted cache hits cost zero credits. Open the playground →