# Snapchat AR Lens Metadata & Related Spotlight Finder (`vexaloom-labs/snapchat-ar-lens-metadata-and-related-spotlight`) Actor

Get trending Snapchat AR lenses, full lens details (creator, previews, related lenses, Spotlight videos using it) by URL or UUID, or lens search results by keyword. No login needed.

- **URL**: https://apify.com/vexaloom-labs/snapchat-ar-lens-metadata-and-related-spotlight.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Social media, Videos, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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

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

#### Example: two lenses with related lenses and Spotlight enrichment

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

#### Example: search the Explore lens tab

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

#### Example: detail without enrichment

```json
{
  "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.

# Actor input Schema

## `mode` (type: `string`):

Browse the public lens charts, fetch specific lenses, or search the Explore lens tab.

## `category` (type: `string`):

(mode=home) Which public Snapchat lens chart to page through. For You, Trending and Face are the deepest charts; World, Music and Live are shorter.

## `lensUrlsOrIds` (type: `array`):

(mode=detail) Lens page URLs (snapchat.com/lens/{uuid}), unlock URLs with a uuid= parameter, or bare 32-character UUIDs.

## `keywords` (type: `array`):

(mode=search) Keywords, brands or creator names to search on the public Snapchat Explore lens tab. Snapchat returns at most 24 lenses per keyword.

## `includeMoreLenses` (type: `boolean`):

(mode=detail) Include the related lenses Snapchat shows beside the lens. Up to 12 are returned; the lens itself is excluded when Snapchat includes it.

## `includeSpotlightsUsingLens` (type: `boolean`):

(mode=detail) Include Spotlight videos that use this lens, with thumbnails, media URLs, creator details, engagement counts and AI-generated descriptions when public.

## `maxItems` (type: `integer`):

Global cap on saved records. Home mode pages through the selected chart until this cap or the end of the chart; the other modes stop when their inputs are exhausted.

## `proxyConfiguration` (type: `object`):

Optional proxy override. Snapchat's public lens pages work without a proxy; leave this empty unless you hit rate limiting.

## Actor input object example

```json
{
  "mode": "home",
  "category": "for_you",
  "lensUrlsOrIds": [
    "565e7595ec4e4a0da689762b127308ef"
  ],
  "keywords": [
    "food"
  ],
  "includeMoreLenses": true,
  "includeSpotlightsUsingLens": true,
  "maxItems": 24
}
```

# Actor output Schema

## `lenses` (type: `string`):

Dataset containing every scraped Snapchat lens, related lens and Spotlight-usage row.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "home",
    "category": "for_you",
    "lensUrlsOrIds": [
        "565e7595ec4e4a0da689762b127308ef"
    ],
    "keywords": [
        "food"
    ],
    "includeMoreLenses": true,
    "includeSpotlightsUsingLens": true,
    "maxItems": 24
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/snapchat-ar-lens-metadata-and-related-spotlight").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "home",
    "category": "for_you",
    "lensUrlsOrIds": ["565e7595ec4e4a0da689762b127308ef"],
    "keywords": ["food"],
    "includeMoreLenses": True,
    "includeSpotlightsUsingLens": True,
    "maxItems": 24,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/snapchat-ar-lens-metadata-and-related-spotlight").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "home",
  "category": "for_you",
  "lensUrlsOrIds": [
    "565e7595ec4e4a0da689762b127308ef"
  ],
  "keywords": [
    "food"
  ],
  "includeMoreLenses": true,
  "includeSpotlightsUsingLens": true,
  "maxItems": 24
}' |
apify call vexaloom-labs/snapchat-ar-lens-metadata-and-related-spotlight --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/snapchat-ar-lens-metadata-and-related-spotlight"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/jmrqhxVYbhWWAmj0W/builds/h0iKfwqSwh7BxMhin/openapi.json