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

AlexandriaSEOAvailable now

Upspring · Search ads

upspring/ads/search

Get SEO and search ranking data with Upspring · Search ads from Alexandria through one Spiral API key. 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. 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
q requiredtext—

Free-text brief, for example prebiotic soda or greens powder daily drink. Hybrid semantic and keyword match.

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.

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/search",
    "input": {
      "q": "<q>"
    }
  }'

Frequently asked questions

How much does Upspring · Search 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 · Search ads through an API?

Send `POST /v1/runs` with `"provider": "alexandria"`, `"model": "upspring/ads/search"` 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 · Search ads?

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

Can my AI agent use Upspring · Search ads?

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