Snapchat AR Lens Metadata & Related Spotlight Finder

Snapchat's public lens pages are a catalog of AR effects: each one carries a creator credit, preview media, a Snapcode, related lenses and the Spotlight videos that were recorded with it. This actor reads those pages directly over HTTP. It can page through the lens charts, open specific lenses by URL or UUID, and search the Explore lens tab. No Snapchat account, cookies or proxy are required.

What this actor does

• Chart mode: pages through the public lens charts — For You, Trending, Face, World, Music and Live — following Snapchat's own cursor until the chart ends or maxItems is reached.
• Detail mode: accepts lens page URLs, unlock URLs or bare UUIDs and returns the full lens record, the related lenses shown beside it, and the Spotlight videos using it.
• Spotlight enrichment: batches every related Spotlight ID through Snapchat's public metadata endpoint to add creator identity, caption, hashtags, media URL, view/share/boost/recommend/comment counts and AI-generated title, description and keywords.
• Search mode: reads the public Explore lens tab for each keyword and returns up to the 24 lens cards Snapchat renders for that query.
• Omits fields the source does not provide, at every nesting level, instead of returning blanks or nulls.

Output per lens record

Chart and detail records share one field set; Explore search records use the lighter set Snapchat exposes on search cards.

Chart / detail lens (source: "home" or "detail")

• scannableUuid — the lens UUID used in its page and unlock URLs.
• lensName, lensId — display name and internal numeric ID.
• lensCreatorDisplayName, lensCreatorUsername, userProfileUrl — creator identity when Snapchat publishes it.
• lensPreviewImageUrl, lensPreviewVideoUrl — static and animated previews.
• iconUrl — the square carousel icon.
• unlockUrl — the URL that opens the lens in Snapchat.
• snapcodeImageUrl — the Snapcode image exposed on the lens page.
• lensCreatorSearchTags — discoverability tags set by the creator.
• isOfficialSnapLens — whether Snapchat marks the lens as official.
• lastUpdatedAt — ISO timestamp when Snapchat exposes a non-zero update epoch.
• lensUrl — the canonical snapchat.com/lens/{uuid} page.
• category — the chart used (home mode only).
• source, scrapedAt — origin and fetch timestamp.
• moreLenses — up to 12 related lenses on detail records, each with the same lens fields (the lens itself is excluded when present).
• spotlightsUsingThisLens — related Spotlight videos on detail records.

Related Spotlight entry (spotlightsUsingThisLens[])

• snapId, storyPageUrl, contentUrl — Spotlight identity and links.
• thumbnailUrl — video poster.
• uploadedAt, durationMs, width, height — video facts from the lens page.
• embeddedTextCaption, keywords, description, name — page-level text when present.
• creatorUsername, creatorDisplayName, creatorIsOfficial — creator identity from hydration.
• caption, hashtags, videoUrl — post text, hashtags and the direct media URL.
• viewCount, shareCount, boostCount, recommendCount, commentCount — public engagement counters.
• aiTitle, aiDescription, aiKeywords — Snapchat's AI-generated summary fields when available.

Removed or private Spotlight videos keep the page-level fields and simply omit the hydration fields.

Explore search result (source: "search")

• lensId, lensName, scannableUuid, lensUrl.
• iconUrl, unlockUrl, thumbnailUrl — icon, unlock link and preview thumbnail.
• creatorName, creatorIsOfficial — creator credit from the card.
• searchKeyword, source, scrapedAt.

If a page cannot be fetched or parsed, the actor saves a short row with error (plus input or searchKeyword) instead of silently dropping it.

Input

Field	Type	Default	Description
mode	string	home	home (browse charts), detail (specific lenses) or search (Explore lens tab).
category	string	for_you	Chart to page through in home: for_you, trending, face, world, music, web_live.
lensUrlsOrIds	array	–	Lens page URLs, unlock URLs or bare UUIDs for detail.
keywords	array	–	Keywords, brands or creator names for search.
includeMoreLenses	boolean	true	Include the related lenses on detail records.
includeSpotlightsUsingLens	boolean	true	Include and hydrate the related Spotlight videos on detail records.
maxItems	integer	100	Global record cap; home mode pages until this cap or the chart ends.
proxyConfiguration	object	–	Optional proxy override; public lens pages work without one.

Example: page through the Trending chart

{
  "mode": "home",
  "category": "trending",
  "maxItems": 72
}

Example: two lenses with related lenses and Spotlight enrichment

{
  "mode": "detail",
  "lensUrlsOrIds": [
    "https://www.snapchat.com/lens/565e7595ec4e4a0da689762b127308ef",
    "dc98faf460f54b7fb6e119d4d7b7c0c3"
  ],
  "includeMoreLenses": true,
  "includeSpotlightsUsingLens": true
}

Example: search the Explore lens tab

{
  "mode": "search",
  "keywords": ["food", "plumbing", "हिंदी"]
}

Example: detail without enrichment

{
  "mode": "detail",
  "lensUrlsOrIds": ["565e7595ec4e4a0da689762b127308ef"],
  "includeMoreLenses": false,
  "includeSpotlightsUsingLens": false
}

Use cases

• Monitor which AR lenses Snapchat is promoting in each chart over time.
• Pull a lens's creator, preview media and Snapcode for a creative or brand-safety review.
• Find the Spotlight videos that used a lens, with their view and reaction counts.
• Discover adjacent lenses through the related-lens list.
• Research which lenses appear for a brand, trend or topic in Explore search.

FAQ

How deep can chart mode go?

For You, Trending and Face keep serving pages for many cursors; World, Music and Live are shorter and end after a few pages. The actor follows cursor_id until Snapchat reports no more pages or maxItems is reached, so raise maxItems when you need the long tail.

Why does search return at most 24 lenses per keyword?

The Explore lens tab renders one 24-card page. Snapchat does not expose a cursor or page parameter on that tab; probing cursor_id, page, offset and similar parameters returns the same cards. Use narrower keywords to partition a topic.

Why do some related Spotlights have no view counts?

The lens page lists up to 16 related Spotlights, but some have been removed or made private by the time the actor hydrates them. Those entries keep the page-level thumbnail, timestamp and caption, and omit the hydration fields rather than inventing numbers.

Why are some creator fields missing?

Snapchat only publishes lensCreatorUsername and userProfileUrl for some lenses, mostly non-official creator lenses. Chart entries and official lenses often leave those fields empty; the record omits them instead of returning a blank.

What is snapcodeImageUrl?

The Snapcode image Snapchat renders on the lens page. It is separate from iconUrl, which is the small carousel icon, and from the unlockUrl, which opens the lens in the Snapchat app.

Are view or share counts available for the lens itself?

No. Snapchat's public lens page does not expose engagement numbers for the lens. Engagement counts in this actor belong to the related Spotlight videos that used the lens.

Does the actor need a proxy or login?

No. Every surface used here is public and works cookieless. The optional proxyConfiguration field exists only as an override for unusual rate limiting.

What happens if Snapchat changes its page structure?

The actor returns an error row for the affected input and logs the failure. It never fabricates a partial record to hide an upstream change.

Is this affiliated with Snapchat?

No. This is an independent tool that reads public Snapchat pages and is not operated or endorsed by Snap Inc.