---
type: "firecrawl-provider"
description: "Competitor ad intelligence from Upspring: Meta ads with their hooks, personas and offers, and the brands behind them."
use_when: "Competitor Meta ads: search, browse, creative breakdowns, detail and similar ads.\n\nBrands that advertise: lookup by name or domain, briefs, peers, similar brands and head-to-head comparison.\n\nVertical, category and creative-dimension ids the filters accept."
categories: "Marketing"
capabilities: 14
pricing: "0–100 credits per billed unit; see each capability for its unit and maximum."
---
# Upspring on Firecrawl Alexandria

Competitor ad intelligence from Upspring: Meta ads with their hooks, personas and offers, and the brands behind them.

- Categories: Marketing
- Category index: [Marketing category](https://firecrawl.dev/alexandria/agents/categories/marketing)
- Provider key: `upspring`
- Access: Firecrawl credits
- Cost (Search ads): 50 credits per non-empty page
- Cost (Browse ads): 50 credits per non-empty page
- Cost (Creative breakdown): 50 credits per non-empty breakdown
- Cost (Ad detail): 100 credits per ad
- Cost (Similar ads): 50 credits per non-empty result
- Cost (Find advertisers): 50 credits per non-empty page
- Cost (Advertiser by domain): 100 credits per available advertiser
- Cost (Advertiser brief): 100 credits per available advertiser
- Cost (Request an advertiser): 0 credits per call
- Cost (Similar advertisers): 50 credits per non-empty result
- Cost (Peer advertisers): 50 credits per non-empty result
- Cost (Compare advertisers): 100 credits per comparison
- Cost (Verticals and categories): 0 credits per call
- Cost (Vertical vocabulary): 0 credits per call

## More

- [Human guide](https://firecrawl.dev/app/alexandria/upspring)
- [OpenAPI spec](https://firecrawl.dev/alexandria/agents/providers/upspring/openapi.json)

## Capabilities

- [Search ads](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/search): {data: ads, meta: {order, note, next_cursor}}. Pass meta.next_cursor back as cursor for the next page; null on the last.
- [Browse ads](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/browse): {data: ads, meta: {order, note, next_cursor}}. Pass meta.next_cursor back as cursor for the next page; null on the last.
- [Creative breakdown](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/breakdown): {data: rows, meta: {note}}: each value's share of the matching ads, unpaginated. Tag dimensions are multi-label, so their shares need not sum to 1.
- [Ad detail](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/detail): {data: ad}: the creative breakdown, its offer, landing page with an ad-to-page coherence score, and store product data when the page is a product page.
- [Similar ads](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/similar): {data: {same_brand, same_vertical}}: the advertiser's closest other ads, and the closest ads from other brands in the vertical.
- [Find advertisers](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/search): {data: advertisers, meta: {note, next_cursor}}. name, domain and fb_page match any; the scope filters AND in. Ranked by match strength, else ad volume.
- [Advertiser by domain](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/by-domain): {data: brief}. status is ready, pending (partial: poll again after refetch_after seconds) or unavailable (minimal {domain, status}, not charged). Fields of a ready brief can still fill in over time.
- [Advertiser brief](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/brief): {data: brief}. status is ready, pending (partial: poll again after refetch_after seconds) or unavailable (minimal {domain, status}, not charged). Fields of a ready brief can still fill in over time.
- [Request an advertiser](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/request): {data: {id, status, refetch_after?, name?, category?, domain?, geo?}}. ready: already available, nothing happens. pending: being fulfilled; poll advertisers/brief.
- [Similar advertisers](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/similar): {data: advertisers}: ranked by creative and market similarity. A brand with no scored neighbours returns an empty list.
- [Peer advertisers](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/peers): {data: advertisers, meta: {note}}: same row shape as advertisers/search. A tier match means the same grade band as this advertiser; meta.note names facets dropped for lack of signal.
- [Compare advertisers](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/compare): {data: comparison}: dimension-by-dimension shares and divergence, whitespace each runs that the other does not, shared and exclusive trends, a similarity score and a short contrast narrative.
- [Verticals and categories](https://firecrawl.dev/alexandria/agents/providers/upspring/taxonomy/verticals): {data: verticals}: every vertical with its categories, the ids the vertical and category filters take.
- [Vertical vocabulary](https://firecrawl.dev/alexandria/agents/providers/upspring/taxonomy/vertical): {data: vertical}: its categories and the dimension vocabularies (hook archetypes, personas, mechanisms, funnel stages and more) used in that vertical.

## 1. Choose this provider when

Competitor Meta ads: search, browse, creative breakdowns, detail and similar ads.

Brands that advertise: lookup by name or domain, briefs, peers, similar brands and head-to-head comparison.

Vertical, category and creative-dimension ids the filters accept.

## 2. Minimal request

Call `POST https://api.firecrawl.dev/v2/scrape` with `{ alexandria: { provider, capability, options } }`. For a batch, send `{ alexandria: [...] }` with up to 10 calls.

```json
{
  "provider": "upspring",
  "capability": "ads/search",
  "options": {
    "q": "<q>",
    "limit": 10
  }
}
```

## 3. Add provider options

Use only the options needed for the task:

- `q` (string, required): Free-text brief, for example prebiotic soda or greens powder daily drink. Hybrid semantic and keyword match. Example: `<q>`
- `vertical` (string[]): Vertical id(s), for example beverages or skincare. Ids come from taxonomy/verticals. Example: `[]`
- `category` (string): One category id within a vertical, from taxonomy/verticals. Example: `<category>`
- `advertiser_id` (string[]): Only ads from these advertiser ids. Example: `[]`
- `is_active` (string): true for ads running now, false for stopped ones. Omit for both. Example: `true`
- `recency_days` (number): Only ads first seen in the last N days (1 to 365). Example: `10`
- `has_product` (string): true for ads whose landing page has store data (price, vendor), false for ads without. Omit for both. Example: `true`
- `min_impressions` (number): Winners-only floor on Meta's 1 to 5 delivery-strength indicator. Excludes ads without one. Example: `5`
- `media_type` (string[]): Only ads with this media type id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `hook_archetype` (string[]): Only ads with this hook archetype id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `hook_polarity` (string[]): Only ads with this hook polarity id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `funnel` (string[]): Only ads with this funnel id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `persona` (string[]): Only ads with this persona id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `archetype` (string[]): Only ads with this archetype id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `mechanism` (string[]): Only ads with this mechanism id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `positioning` (string[]): Only ads with this positioning id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `offer_type` (string[]): Only ads with this offer type id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `persuasion_technique` (string[]): Only ads that use this persuasion technique (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `claim_type` (string[]): Only ads that use this claim type (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `evidence_type` (string[]): Only ads that use this evidence type (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `limit` (number): Ads per page, 1 to 100 (1 to 50 with include=descriptors). Default 25. Example: `10`
- `include` (string): Comma-separated: descriptors adds synopsis and long_form narration per ad (token-heavy); media adds durable {video_url, image_url, thumbnail_url, width, height}. Example: `<include>`
- `cursor` (string): meta.next_cursor from the previous page, verbatim. Send the same filters with it; a cursor replayed with changed filters is refused. Example: `<cursor>`

## 4. Request through your preferred interface

### JavaScript

```javascript
const result = await firecrawl.scrape({
  alexandria: {
    provider: "upspring",
    capability: "ads/search",
    options: {
      q: "<q>",
      limit: 10,
    },
  },
});
```

### Python

```python
result = firecrawl.scrape_alexandria({
  "provider": "upspring",
  "capability": "ads/search",
  "options": {
    "q": "<q>",
    "limit": 10
  }
})
```

### cURL

```sh
curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "alexandria": {
    "provider": "upspring",
    "capability": "ads/search",
    "options": {
      "q": "<q>",
      "limit": 10
    }
  }
}'
```

### CLI

```sh
firecrawl scrape 'upspring/ads/search' \
  --options '{"q":"<q>","limit":10}'
```


### MCP

Call the FCX MCP retrieve tool with this object:

```json
{
  "provider": "upspring",
  "capability": "ads/search",
  "options": {
    "q": "<q>",
    "limit": 10
  }
}
```

Ask for only the returned fields needed by the task.

## 5. Full request shape

```json
{
  "provider": "upspring",
  "capability": "ads/search",
  "options": {
    "q": "<q>",
    "limit": 10
  }
}
```

## 6. Response data

The response includes `success`, `provider`, `capability`, `creditsCost` and `data`. This example shows the provider payload in `data`:

```json
{
  "data": [
    {
      "id": "<id>",
      "advertiser": {},
      "media_type": "<media_type>",
      "is_active": false,
      "started_at": "<started_at>",
      "dimensions": {},
      "one_line": "<one_line>",
      "hook_text": "<hook_text>",
      "strength": {},
      "ad_library_url": "<ad_library_url>"
    }
  ]
}
```

## API reference-derived contract

The following capability contract is generated from the same normalized Alexandria API reference exposed in the API spec.

### Search ads

- Capability: `ads/search`
- Description: {data: ads, meta: {order, note, next_cursor}}. Pass meta.next_cursor back as cursor for the next page; null on the last.
- Instructions: Use to find Meta ads matching a free-text idea, relevance-ranked across Upspring's competitor ad corpus. Re-rank the page by strength.impressions, then open the finalists with ads/detail. For the newest or best-performing ads without a query use ads/browse.
- Cost: 50 credits per non-empty page
- Capability file: [Search ads](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/search)

Accepted options:
- `q` (string, required): Free-text brief, for example prebiotic soda or greens powder daily drink. Hybrid semantic and keyword match. Example: `<q>`
- `vertical` (string[]): Vertical id(s), for example beverages or skincare. Ids come from taxonomy/verticals. Example: `[]`
- `category` (string): One category id within a vertical, from taxonomy/verticals. Example: `<category>`
- `advertiser_id` (string[]): Only ads from these advertiser ids. Example: `[]`
- `is_active` (string): true for ads running now, false for stopped ones. Omit for both. Example: `true`
- `recency_days` (number): Only ads first seen in the last N days (1 to 365). Example: `10`
- `has_product` (string): true for ads whose landing page has store data (price, vendor), false for ads without. Omit for both. Example: `true`
- `min_impressions` (number): Winners-only floor on Meta's 1 to 5 delivery-strength indicator. Excludes ads without one. Example: `5`
- `media_type` (string[]): Only ads with this media type id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `hook_archetype` (string[]): Only ads with this hook archetype id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `hook_polarity` (string[]): Only ads with this hook polarity id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `funnel` (string[]): Only ads with this funnel id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `persona` (string[]): Only ads with this persona id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `archetype` (string[]): Only ads with this archetype id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `mechanism` (string[]): Only ads with this mechanism id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `positioning` (string[]): Only ads with this positioning id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `offer_type` (string[]): Only ads with this offer type id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `persuasion_technique` (string[]): Only ads that use this persuasion technique (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `claim_type` (string[]): Only ads that use this claim type (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `evidence_type` (string[]): Only ads that use this evidence type (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `limit` (number): Ads per page, 1 to 100 (1 to 50 with include=descriptors). Default 25. Example: `10`
- `include` (string): Comma-separated: descriptors adds synopsis and long_form narration per ad (token-heavy); media adds durable {video_url, image_url, thumbnail_url, width, height}. Example: `<include>`
- `cursor` (string): meta.next_cursor from the previous page, verbatim. Send the same filters with it; a cursor replayed with changed filters is refused. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "advertiser": {},
      "media_type": "<media_type>",
      "is_active": false,
      "started_at": "<started_at>",
      "dimensions": {},
      "one_line": "<one_line>",
      "hook_text": "<hook_text>",
      "strength": {},
      "ad_library_url": "<ad_library_url>"
    }
  ]
}
```

### Browse ads

- Capability: `ads/browse`
- Description: {data: ads, meta: {order, note, next_cursor}}. Pass meta.next_cursor back as cursor for the next page; null on the last.
- Instructions: Use to list a brand's or a vertical's ads by filter: what an advertiser is running now (advertiser_id + is_active=true), or the winners in a category (order_by=best, min_impressions=4).
- Cost: 50 credits per non-empty page
- Capability file: [Browse ads](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/browse)

Accepted options:
- `vertical` (string[]): Vertical id(s), for example beverages or skincare. Ids come from taxonomy/verticals. Example: `[]`
- `category` (string): One category id within a vertical, from taxonomy/verticals. Example: `<category>`
- `advertiser_id` (string[]): Only ads from these advertiser ids. Example: `[]`
- `is_active` (string): true for ads running now, false for stopped ones. Omit for both. Example: `true`
- `recency_days` (number): Only ads first seen in the last N days (1 to 365). Example: `10`
- `has_product` (string): true for ads whose landing page has store data (price, vendor), false for ads without. Omit for both. Example: `true`
- `min_impressions` (number): Winners-only floor on Meta's 1 to 5 delivery-strength indicator. Excludes ads without one. Example: `5`
- `media_type` (string[]): Only ads with this media type id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `hook_archetype` (string[]): Only ads with this hook archetype id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `hook_polarity` (string[]): Only ads with this hook polarity id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `funnel` (string[]): Only ads with this funnel id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `persona` (string[]): Only ads with this persona id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `archetype` (string[]): Only ads with this archetype id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `mechanism` (string[]): Only ads with this mechanism id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `positioning` (string[]): Only ads with this positioning id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `offer_type` (string[]): Only ads with this offer type id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `persuasion_technique` (string[]): Only ads that use this persuasion technique (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `claim_type` (string[]): Only ads that use this claim type (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `evidence_type` (string[]): Only ads that use this evidence type (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `order_by` (string): random (a fresh sample each call), recent, or best (performance-signal ranked). Example: `random`
- `limit` (number): Ads per page, 1 to 100 (1 to 50 with include=descriptors). Default 25. Example: `10`
- `include` (string): Comma-separated: descriptors adds synopsis and long_form narration per ad (token-heavy); media adds durable {video_url, image_url, thumbnail_url, width, height}. Example: `<include>`
- `cursor` (string): meta.next_cursor from the previous page, verbatim. Send the same filters with it; a cursor replayed with changed filters is refused. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "advertiser": {},
      "media_type": "<media_type>",
      "is_active": false,
      "started_at": "<started_at>",
      "dimensions": {},
      "one_line": "<one_line>",
      "hook_text": "<hook_text>",
      "strength": {},
      "ad_library_url": "<ad_library_url>"
    }
  ]
}
```

### Creative breakdown

- Capability: `ads/breakdown`
- Description: {data: rows, meta: {note}}: each value's share of the matching ads, unpaginated. Tag dimensions are multi-label, so their shares need not sum to 1.
- Instructions: Use for how a market advertises: the share of hooks, personas, offers or formats across a vertical, brand or filter. Run it twice, once with min_impressions=4, to see what the winning ads over-index on.
- Cost: 50 credits per non-empty breakdown
- Capability file: [Creative breakdown](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/breakdown)

Accepted options:
- `group_by` (string, required): Dimension to break the matching ads down by. Example: `media_type`
- `vertical` (string[]): Vertical id(s), for example beverages or skincare. Ids come from taxonomy/verticals. Example: `[]`
- `category` (string): One category id within a vertical, from taxonomy/verticals. Example: `<category>`
- `advertiser_id` (string[]): Only ads from these advertiser ids. Example: `[]`
- `is_active` (string): true for ads running now, false for stopped ones. Omit for both. Example: `true`
- `recency_days` (number): Only ads first seen in the last N days (1 to 365). Example: `10`
- `has_product` (string): true for ads whose landing page has store data (price, vendor), false for ads without. Omit for both. Example: `true`
- `min_impressions` (number): Winners-only floor on Meta's 1 to 5 delivery-strength indicator. Excludes ads without one. Example: `5`
- `media_type` (string[]): Only ads with this media type id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `hook_archetype` (string[]): Only ads with this hook archetype id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `hook_polarity` (string[]): Only ads with this hook polarity id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `funnel` (string[]): Only ads with this funnel id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `persona` (string[]): Only ads with this persona id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `archetype` (string[]): Only ads with this archetype id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `mechanism` (string[]): Only ads with this mechanism id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `positioning` (string[]): Only ads with this positioning id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `offer_type` (string[]): Only ads with this offer type id (OR across values). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `persuasion_technique` (string[]): Only ads that use this persuasion technique (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `claim_type` (string[]): Only ads that use this claim type (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`
- `evidence_type` (string[]): Only ads that use this evidence type (an ad can carry several). Ids from taxonomy/vertical's dimensions. Example: `[]`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "label": "<label>",
      "description": "<description>",
      "share": 0
    }
  ]
}
```

### Ad detail

- Capability: `ads/detail`
- Description: {data: ad}: the creative breakdown, its offer, landing page with an ad-to-page coherence score, and store product data when the page is a product page.
- Instructions: Use for everything about one ad: the hook, offer, landing page and whether the page delivers what the ad promises. Add include=full for scenes, transcript, overlays and narrative.
- Cost: 100 credits per ad
- Capability file: [Ad detail](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/detail)

Accepted options:
- `id` (string, required): Ad id from an ads/search, ads/browse or ads/similar row. Example: `<id>`
- `include` (string): Comma-separated deep blocks: scenes, transcript, overlays, narrative, full (those four), media (asset URLs, not part of full). Example: `<include>`

Response schema example:
```json
{
  "data": {
    "id": "<id>",
    "advertiser": {},
    "media_type": "<media_type>",
    "is_active": false,
    "started_at": "<started_at>",
    "dimensions": {},
    "one_line": "<one_line>",
    "hook_text": "<hook_text>",
    "strength": {},
    "ad_library_url": "<ad_library_url>",
    "offer": {},
    "landing_page": {},
    "product": {}
  }
}
```

### Similar ads

- Capability: `ads/similar`
- Description: {data: {same_brand, same_vertical}}: the advertiser's closest other ads, and the closest ads from other brands in the vertical.
- Instructions: Use to find ads creatively like one ad, from the same brand and from its competitors.
- Cost: 50 credits per non-empty result
- Capability file: [Similar ads](https://firecrawl.dev/alexandria/agents/providers/upspring/ads/similar)

Accepted options:
- `id` (string, required): Ad id from an ads/search, ads/browse or ads/similar row. Example: `<id>`
- `include` (string): descriptors adds synopsis and long_form per ad. Example: `descriptors`

Response schema example:
```json
{
  "data": {
    "same_brand": [],
    "same_vertical": []
  }
}
```

### Find advertisers

- Capability: `advertisers/search`
- Description: {data: advertisers, meta: {note, next_cursor}}. name, domain and fb_page match any; the scope filters AND in. Ranked by match strength, else ad volume.
- Instructions: Use to find a brand's advertiser id by name, website or Facebook page, or to list the advertisers in a vertical, category or size tier. For one brand from its domain with the full brief in one call use advertisers/by-domain.
- Cost: 50 credits per non-empty page
- Capability file: [Find advertisers](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/search)

Accepted options:
- `name` (string): Fuzzy brand name, typo and accent tolerant. Example: `<name>`
- `domain` (string): Website: full URL, bare domain, name without TLD or a partial term. Example: `<domain>`
- `fb_page` (string): Facebook page URL or numeric page id (exact); a vanity URL falls back to a name match. Example: `<fb_page>`
- `vertical` (string[]): Vertical id(s), for example beverages or skincare. Ids come from taxonomy/verticals. Example: `[]`
- `category` (string): One category id within a vertical, from taxonomy/verticals. Example: `<category>`
- `geo` (string): Primary geography, for example US. Example: `<geo>`
- `min_ads` (number): Only advertisers with at least this many active ads. Example: `10`
- `spend_tier` (string): Only advertisers whose spend scale grade is this tier or bigger (D < C < B < A < A+). Coarse estimates, never exact figures. Example: `D`
- `traffic_tier` (string): Only advertisers whose traffic scale grade is this tier or bigger (D < C < B < A < A+). Coarse estimates, never exact figures. Example: `D`
- `sales_tier` (string): Only advertisers whose sales scale grade is this tier or bigger (D < C < B < A < A+). Coarse estimates, never exact figures. Example: `D`
- `limit` (number): Advertisers per page, 1 to 50. Default 25. Example: `10`
- `cursor` (string): meta.next_cursor from the previous page, verbatim. Send the same filters with it; a cursor replayed with changed filters is refused. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "name": "<name>",
      "domain": "<domain>",
      "vertical": {},
      "category": {},
      "subcategories": [],
      "dominant": {},
      "geo": "<geo>",
      "active_ads": 0,
      "enrichment": {}
    }
  ]
}
```

### Advertiser by domain

- Capability: `advertisers/by-domain`
- Description: {data: brief}. status is ready, pending (partial: poll again after refetch_after seconds) or unavailable (minimal {domain, status}, not charged). Fields of a ready brief can still fill in over time.
- Instructions: Use when all you have is a company's website: resolves it to one advertiser and returns the same brief as advertisers/brief. Never 404s; a domain Upspring cannot source answers status unavailable and is not charged.
- Cost: 100 credits per available advertiser
- Capability file: [Advertiser by domain](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/by-domain)

Accepted options:
- `domain` (string, required): Company domain or URL, for example mudwtr.com; normalized to the root domain. Example: `<domain>`
- `sync` (string): true (default) waits a few seconds for a brand Upspring has to fetch; false answers pending at once. Example: `true`

Response schema example:
```json
{
  "data": {
    "id": "<id>",
    "name": "<name>",
    "status": "<status>",
    "refetch_after": 0,
    "domain": "<domain>",
    "vertical": {},
    "category": {},
    "summary": {},
    "enrichment": {},
    "social": {},
    "reddit": {},
    "signals": {},
    "hook_themes": [],
    "top_ads": []
  }
}
```

### Advertiser brief

- Capability: `advertisers/brief`
- Description: {data: brief}. status is ready, pending (partial: poll again after refetch_after seconds) or unavailable (minimal {domain, status}, not charged). Fields of a ready brief can still fill in over time.
- Instructions: Use for a brand's ad strategy at a glance: size grades, Facebook and Instagram followers, Reddit sentiment, its creative fingerprint (personas, mechanisms, hooks, media mix, funnel), hook themes and its top ads.
- Cost: 100 credits per available advertiser
- Capability file: [Advertiser brief](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/brief)

Accepted options:
- `id` (string, required): Advertiser id from advertisers/search, advertisers/by-domain or an ad's advertiser.id. It is the brand's Facebook page id. Example: `<id>`

Response schema example:
```json
{
  "data": {
    "id": "<id>",
    "name": "<name>",
    "status": "<status>",
    "refetch_after": 0,
    "domain": "<domain>",
    "vertical": {},
    "category": {},
    "summary": {},
    "enrichment": {},
    "social": {},
    "reddit": {},
    "signals": {},
    "hook_themes": [],
    "top_ads": []
  }
}
```

### Request an advertiser

- Capability: `advertisers/request`
- Description: {data: {id, status, refetch_after?, name?, category?, domain?, geo?}}. ready: already available, nothing happens. pending: being fulfilled; poll advertisers/brief.
- Instructions: Use when advertisers/brief answers not found or status unavailable for an advertiser id you know exists: asks Upspring to source it, then poll advertisers/brief. Idempotent; each new advertiser counts against a daily limit.
- Cost: 0 credits per call
- Capability file: [Request an advertiser](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/request)

Accepted options:
- `id` (string, required): Advertiser id from advertisers/search, advertisers/by-domain or an ad's advertiser.id. It is the brand's Facebook page id. Example: `<id>`

Response schema example:
```json
{
  "data": {
    "id": "<id>",
    "status": "<status>",
    "refetch_after": 0
  }
}
```

### Similar advertisers

- Capability: `advertisers/similar`
- Description: {data: advertisers}: ranked by creative and market similarity. A brand with no scored neighbours returns an empty list.
- Instructions: Use for a brand's closest competitors: advertisers going after the same audience with comparable creative strategies.
- Cost: 50 credits per non-empty result
- Capability file: [Similar advertisers](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/similar)

Accepted options:
- `id` (string, required): Advertiser id from advertisers/search, advertisers/by-domain or an ad's advertiser.id. It is the brand's Facebook page id. Example: `<id>`
- `limit` (number): Advertisers to return, 1 to 25. Default 10. Example: `10`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "name": "<name>",
      "score": 0,
      "rank": 0
    }
  ]
}
```

### Peer advertisers

- Capability: `advertisers/peers`
- Description: {data: advertisers, meta: {note}}: same row shape as advertisers/search. A tier match means the same grade band as this advertiser; meta.note names facets dropped for lack of signal.
- Instructions: Use for brands like this one: same category, vertical, geography or size band. For creative similarity instead use advertisers/similar.
- Cost: 50 credits per non-empty result
- Capability file: [Peer advertisers](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/peers)

Accepted options:
- `id` (string, required): Advertiser id from advertisers/search, advertisers/by-domain or an ad's advertiser.id. It is the brand's Facebook page id. Example: `<id>`
- `match` (string): Comma-separated facets to share with this advertiser: vertical, category, geo, spend_tier, traffic_tier, sales_tier. Default category,spend_tier. Example: `category,spend_tier`
- `limit` (number): Advertisers to return, 1 to 25. Default 10. Example: `10`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "name": "<name>",
      "domain": "<domain>",
      "vertical": {},
      "category": {},
      "subcategories": [],
      "dominant": {},
      "geo": "<geo>",
      "active_ads": 0,
      "enrichment": {}
    }
  ]
}
```

### Compare advertisers

- Capability: `advertisers/compare`
- Description: {data: comparison}: dimension-by-dimension shares and divergence, whitespace each runs that the other does not, shared and exclusive trends, a similarity score and a short contrast narrative.
- Instructions: Use to put two brands' ad strategies side by side: where they overlap, where they differ, and what each leaves open.
- Cost: 100 credits per comparison
- Capability file: [Compare advertisers](https://firecrawl.dev/alexandria/agents/providers/upspring/advertisers/compare)

Accepted options:
- `id` (string, required): Advertiser id from advertisers/search, advertisers/by-domain or an ad's advertiser.id. It is the brand's Facebook page id. Example: `<id>`
- `otherId` (string, required): The second advertiser's id. Example: `<otherId>`

Response schema example:
```json
{
  "data": {
    "a": {},
    "b": {},
    "dimensions": {},
    "whitespace": {},
    "trends": {},
    "similarity_score": 0,
    "contrast": {}
  }
}
```

### Verticals and categories

- Capability: `taxonomy/verticals`
- Description: {data: verticals}: every vertical with its categories, the ids the vertical and category filters take.
- Instructions: Use first, free, to learn the vertical and category ids the ads and advertiser filters accept.
- Cost: 0 credits per call
- Capability file: [Verticals and categories](https://firecrawl.dev/alexandria/agents/providers/upspring/taxonomy/verticals)

Accepted options:

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "label": "<label>",
      "categories": []
    }
  ]
}
```

### Vertical vocabulary

- Capability: `taxonomy/vertical`
- Description: {data: vertical}: its categories and the dimension vocabularies (hook archetypes, personas, mechanisms, funnel stages and more) used in that vertical.
- Instructions: Use, free, before filtering ads by persona, hook or another dimension: lists the valid ids in one vertical.
- Cost: 0 credits per call
- Capability file: [Vertical vocabulary](https://firecrawl.dev/alexandria/agents/providers/upspring/taxonomy/vertical)

Accepted options:
- `vertical` (string, required): Vertical id from taxonomy/verticals, for example beverages. Example: `<vertical>`

Response schema example:
```json
{
  "data": {
    "id": "<id>",
    "label": "<label>",
    "categories": [],
    "dimensions": {}
  }
}
```