SignalShelf · Developer documentation

Snapchat profile

Sample profile responses are available. Snapchat public profiles and Spotlights use Snap’s Public Profile API, which requires a Snap Business Marketing API OAuth app and API allowlisting. OAuth refresh-token rotation is encrypted and stored in PostgreSQL; local cache-reset checks pass. Snap allowlisting, permitted live validation, and SignalShelf paid-use/retention review are pending; private profiles and Spotlight comments are unavailable.

Request

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

Parameter	Type	Required	Description
`platform`	string	Yes	"snapchat"
`handle`	string	Yes	Public profile username.
`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":"snapchat","handle":"kyliejenner","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: "snapchat", handle: "kyliejenner", 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":"snapchat","handle":"kyliejenner","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": "snapchat",
    "handle": "kyliejenner",
    "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.snapchat.com/@kyliejenner",
    "avatar": null,
    "sample": true,
    "provider": "sample-fixture",
    "details": {
      "category": null,
      "subcategory": null,
      "has_story": false,
      "curated_highlights": 0,
      "spotlight_highlights": 0,
      "snapcode_url": null,
      "hero_image_url": null,
      "updated_at": null,
      "related_accounts": []
    }
  },
  "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.

Snapchat-specific fields (details)

Returned inside data.details.

Field	Type	Description
`details.category`	string \| null	Creator category ID.
`details.subcategory`	string \| null	Creator subcategory ID.
`details.has_story`	boolean	Has a live public story.
`details.curated_highlights`	number	Curated highlights on the profile page.
`details.spotlight_highlights`	number	Spotlight highlights on the profile page.
`details.snapcode_url`	string \| null	Snapcode image URL.
`details.hero_image_url`	string \| null	Profile hero image URL.
`details.updated_at`	string \| null	Last profile update (ISO 8601).
`details.related_accounts`	array	Usernames Snapchat lists as related.

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

Snapchat public profiles and Spotlights use Snap’s Public Profile API, which requires a Snap Business Marketing API OAuth app and API allowlisting. OAuth refresh-token rotation is encrypted and stored in PostgreSQL; local cache-reset checks pass. Snap allowlisting, permitted live validation, and SignalShelf paid-use/retention review are pending; private profiles and Spotlight comments are unavailable.

Only public profiles (creators and businesses) are available; personal accounts are not public.

Snapchat does not expose following or post counts.

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