Spiral gives your agent every tool with one account. Browse the tools →

AlexandriaSEOAvailable now

Upspring · Browse ads

upspring/ads/browse

Get SEO and search ranking data with Upspring · Browse ads from Alexandria through one Spiral API key. 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). It runs in the background and returns structured JSON. Pay as you go, with no subscription.

Pricing

Up to $0.087295 per run.

Limits

Runs
In the background
Returns
json
Longest queue wait
1 hour
Run deadline
5 minutes
Longest run, end to end
225 minutes
Largest inline input
1 MB
Largest input file
2 GB
Largest output
5 GB

Input

FieldKindDefaultDescription
limitnumber
1 to 100
—

Ads per page, 1 to 100 (1 to 50 with include=descriptors). Default 25.

cursortext—

meta.next_cursor from the previous page, verbatim. Send the same filters with it; a cursor replayed with changed filters is refused.

funnellist—

Only ads with this funnel id (OR across values). Ids from taxonomy/vertical's dimensions.

includetext—

Comma-separated: descriptors adds synopsis and long_form narration per ad (token-heavy); media adds durable {video_url, image_url, thumbnail_url, width, height}.

personalist—

Only ads with this persona id (OR across values). Ids from taxonomy/vertical's dimensions.

categorytext—

One category id within a vertical, from taxonomy/verticals.

order_byone of
random, recent, best
random

random (a fresh sample each call), recent, or best (performance-signal ranked).

verticallist—

Vertical id(s), for example beverages or skincare. Ids come from taxonomy/verticals.

archetypelist—

Only ads with this archetype id (OR across values). Ids from taxonomy/vertical's dimensions.

is_activeone of
true, false
—

true for ads running now, false for stopped ones. Omit for both.

mechanismlist—

Only ads with this mechanism id (OR across values). Ids from taxonomy/vertical's dimensions.

claim_typelist—

Only ads that use this claim type (an ad can carry several). Ids from taxonomy/vertical's dimensions.

media_typelist—

Only ads with this media type id (OR across values). Ids from taxonomy/vertical's dimensions.

offer_typelist—

Only ads with this offer type id (OR across values). Ids from taxonomy/vertical's dimensions.

has_productone of
true, false
—

true for ads whose landing page has store data (price, vendor), false for ads without. Omit for both.

positioninglist—

Only ads with this positioning id (OR across values). Ids from taxonomy/vertical's dimensions.

recency_daysnumber
1 to 365
—

Only ads first seen in the last N days (1 to 365).

advertiser_idlist—

Only ads from these advertiser ids.

evidence_typelist—

Only ads that use this evidence type (an ad can carry several). Ids from taxonomy/vertical's dimensions.

hook_polaritylist—

Only ads with this hook polarity id (OR across values). Ids from taxonomy/vertical's dimensions.

hook_archetypelist—

Only ads with this hook archetype id (OR across values). Ids from taxonomy/vertical's dimensions.

min_impressionsnumber
1 to 5
—

Winners-only floor on Meta's 1 to 5 delivery-strength indicator. Excludes ads without one.

persuasion_techniquelist—

Only ads that use this persuasion technique (an ad can carry several). Ids from taxonomy/vertical's dimensions.

Same request in code

curl https://api.spiral.ai/v1/runs \
  -H "Authorization: Bearer $SPIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "provider": "alexandria",
    "model": "upspring/ads/browse",
    "input": {
      "limit": 1
    }
  }'

Frequently asked questions

How much does Upspring · Browse ads cost?

Up to $0.087295 per run. You pay as you go from one Spiral balance, with no subscription, and a failed run is not charged.

How do I use Upspring · Browse ads through an API?

Send `POST /v1/runs` with `"provider": "alexandria"`, `"model": "upspring/ads/browse"` and the input fields on this page, using one Spiral API key. It runs in the background: poll the run, or name a webhook to be told when it finishes.

Do I need an account with Alexandria to use Upspring · Browse ads?

No. Spiral runs it on its own Alexandria account and charges your Spiral balance.

Can my AI agent use Upspring · Browse ads?

Yes. Agents find and run it through Spiral's MCP server, CLI or agent skill, with the same API key.