Meta Marketing API: ads and targeting

What is the Meta Marketing API for?

What ships out of the box

Targeting: from search to reach estimate

Research the audience first, then assemble the targeting and see how many people it covers before anything is created.

import asyncio, os
from socialift import Ads

async def main():
    async with Ads(app_secret=os.environ["FACEBOOK_APP_SECRET"], graph_version="v25.0") as ads:
        token = os.environ["META_USER_TOKEN"]
        interests = await ads.search_interests(token, "fitness")
        targeting = ads.build_targeting(countries=["UZ"], age_min=18, age_max=45,
                                        interests=[{"id": interests[0]["id"]}],
                                        advantage_audience=False)  # exact age range
        print(await ads.delivery_estimate(token, ad_account_id="act_123", targeting=targeting))

asyncio.run(main())

Boosting an Instagram post in one call

boost_post turns an existing post into an ad by creating the campaign, ad set, creative and ad in sequence. Everything stays PAUSED — you review it and switch it on yourself.

import asyncio, os
from socialift import Ads

async def main():
    async with Ads(app_secret=os.environ["FACEBOOK_APP_SECRET"], graph_version="v25.0") as ads:
        token = os.environ["META_USER_TOKEN"]
        result = await ads.boost_post(
            token,
            ad_account_id="act_123",
            ig_user_id="1784...",
            media_id="1790...",
            name="Reels boost",
            daily_budget_major=10.0,  # ad account currency, e.g. USD 10
            goal="traffic",
            link="https://example.uz/offer",
            targeting=ads.build_targeting(countries=["UZ"], age_min=18, platforms=["instagram"]),
        )
        # Results broken down by age and gender
        rows = await ads.insights_rows(
            token, "act_123", level="campaign",
            date_preset="last_7d", breakdowns=["age", "gender"],
        )

asyncio.run(main())

Audiences and pixels

Beyond targeting, audiences let you point ads at a specific group of people.

Custom audience

An audience built from your customer list. add_audience_users normalises emails and phone numbers to Meta's rules and SHA-256-hashes them on your own server where the SDK runs — no plain text reaches Meta. The ad account must have accepted the Custom Audience Terms.

Lookalike audience

People in the chosen country most similar to a source audience. ratio=0.01 is the closest 1% of that country's population; allowed range 0.01–0.20. The source audience needs at least 100 members.

Pixels

The pixels attached to an ad account can be listed through the API.

Lead Ads context

Each lead coming from Lead Ads can carry the targeting context of its campaign and ad set — so you can see which audience produced it.

Launching the ads workflow

1. 1

   Request permissions

   Add ads_management and ads_read to your Meta app. Standard Access covers your own ad accounts; for client accounts get Advanced Access through App Review and Business Verification.

2. 2

   Connect a Facebook account

   Sign in with Facebook on the Connections (Ulanishlar) page of the dashboard: ads calls run on that personal user token.

3. 3

   Research the audience

   Search interests and locations, assemble the targeting and estimate reach without spending.

4. 4

   Create the campaign

   Create a campaign, ad set and ad, or boost an existing Instagram post with boost_post — all PAUSED.

5. 5

   Review, activate and monitor

   Switch the status to ACTIVE, watch results by breakdown and adjust the daily budget.

What to watch when automating ads

• ▸Everything is created PAUSED — nothing is shown until you set it to ACTIVE.
• ▸Pass budgets in the ad account currency's main unit and check them against the minimum daily budget from ad_accounts.
• ▸Re-validate saved interests from time to time — Meta removes outdated ones.
• ▸When you upload a customer list, emails and phone numbers are SHA-256-hashed on the server running the SDK and only the hashes go to Meta.
• ▸Add ads_management and ads_read to your Meta app. Standard Access covers your own ad accounts; for client accounts get Advanced Access through App Review and Business Verification.
• ▸Playground requests are real: actions that affect budgets ask for explicit confirmation there.