Snapchat Spotlight
A public Snapchat Spotlight record can contain a source link, caption, creator identity, media references, publication time, duration, audio details, and visible engagement counts. The normalized result keeps those available fields with a collection timestamp for selected-video review, catalog enrichment, and point-in-time comparison.
Features
- Known Spotlight resolutionSubmit one public snapchat.com URL and resolve the matching detail response into at most one standard record without expanding a feed.
- Creator and video contextKeep the source URL and available caption, author identity, media, duration, audio, hashtags, mentions, and publication time in one fixed result shape.
- Visible engagement snapshotReturn available likes, comments, shares, plays, and views with collected_at so downstream analysis retains the observation time.
Parameters
| Parameters | Required | Description |
|---|---|---|
url | Required | Required non-empty http or https URL whose host is snapchat.com or any of its subdomains. The runtime does not impose a pathname rule; use a public Spotlight link such as /@username/spotlight/{spotlight_id}. |
How to Use
Submit one public Snapchat Spotlight URL, follow the asynchronous task, and read its stored normalized result.
- Copy a public Snapchat Spotlight URL on snapchat.com or one of its subdomains.
- Send the URL as url to /v1/snapchat/spotlight and save the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or reports a failure.
- Read data.results.items; if the stored-result response returns has_more, continue with its next_cursor.
curl -X POST "https://api.socq.ai/v1/snapchat/spotlight" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.snapchat.com/@queenhaley_13/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY2pnZnF0bG52AZslQsUdAZslQoRQAAAAAQ"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items; next_cursor paginates stored results onlyBest Use Cases
- Review a selected Spotlight: Turn a known public link into a traceable record with source, caption, author, media, time, and available engagement fields.
- Enrich a content catalog: Add normalized video identity, creator context, duration, audio, hashtags, mentions, and collection time to an existing URL list.
- Compare captured engagement: Pair visible counts with collected_at when comparing separate observations without treating the values as live or complete.
Pro Tips
- Submit exactly one URL in url; arrays, results_limit, usernames, and callback_url are not accepted by this endpoint.
- Use a public Spotlight link even though validation checks the Snapchat host rather than enforcing a pathname; unrelated Snapchat paths can fail at the provider.
- Do not treat task-result next_cursor as source-feed pagination because the provider lookup is a single detail request with at most one record.
- Allow IDs, captions, author fields, media, timestamps, audio, and individual metrics to be null when the public response omits them.
- Store collected_at beside engagement counts so every measurement remains tied to its collection time.
- Budget 0.19 credits for each successful task; fixed billing does not change with returned fields or result count.
Related APIs
Use these APIs when you need a different type of public Snapchat data.