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

AlexandriaSEOAvailable now

Upspring · Creative breakdown

upspring/ads/breakdown

Get SEO and search ranking data with Upspring · Creative breakdown from Alexandria through one Spiral API key. 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. 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
group_by requiredone of
media_type, hook_archetype, hook_polarity, funnel, persona, archetype, mechanism, positioning, offer_type, persuasion_technique, claim_type, evidence_type
—

Dimension to break the matching ads down by.

funnellist—

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

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/breakdown",
    "input": {
      "group_by": "media_type"
    }
  }'

Frequently asked questions

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

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

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

Can my AI agent use Upspring · Creative breakdown?

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