What the Ads Agent does and its plan
The Ads Agent plan, one for each ad platform with its one ad account. The ad spend is billed by the platform to your own card. The price is on the plans page.
New to the API? Start with Getting started: the key, the address, the errors and the limits.
Getting started with this agent
These are done in the Fly app, signed in, because the API cannot do them.
- Connect the ad accounts in the app, on the Ads page under Accounts. The API cannot connect an account. The tool
fly_connect_linkswithkindsset to["ads"]gives the ads connect page, which opens without signing in, to hand to whoever manages the accounts. In the app: Ads. - Choose the Ads Agent plan for each ad platform. In the app: Billing.
- Make a key on the AI assistants page and give it the Ads Agent. In the app: AI assistants.
- Switch it on for the location with the
settingsop on the account page (changes.enabled_checks.ads_agentset to true), then set how Fly works each ad account withads_account_management_set:managed(Fly runs it),advise(Fly recommends) orread_only(Reference only).
The working loop
- Find the location:
GET /v1/workspaceslists each location with itslocation_id;agents_onholds"ads"where the Ads Agent is switched on. - Read the agent's home:
POST /v1/tools/fly_homewithlocation_idandagent"ads"answers the Ads Agent's cards that need the owner (cards.needs_you), the ones in flight, its recent activity, rank and health. - Decide each card:
POST /v1/locations/{location_id}/ops/respondwith the card'sidasaction_idand adecision(approve,reject,done,dismiss,submit,changeorundo_dismiss). The toolfly_cardgives one card whole first. - Read its report:
POST /v1/tools/fly_reportwithagent"ads"andfromandtodates (YYYY-MM-DD) answers the headline numbers, each section and the first rows of each table; the opads_reporton the account page answers the report whole.
curl -X POST https://www.fly-social.com/api/v1/tools/fly_home \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"location_id":"3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84","agent":"ads"}'Ad accounts and how Fly works them
Start with ads_accounts_list: each account's id is the ads_account_id the other ops take. Set each account's mode, hold one, mark its billing set up, and switch Autopilot on an account Fly runs.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_accounts_list | Read | The place's ad accounts, each with its mode (Fly runs it, Fly recommends, Reference only), its label and its ads manager link. | {} |
ads_account_management_set | Write | Set an ad account to Fly runs it, Fly recommends (Fly reads and recommends, changes nothing) or Reference only (read for reference, no plan needed), with an optional label. | { ads_account_id, management: managed | advise | read_only, owner_label? } |
ads_account_hold | Write | Hold one ad account so the Ads Agent plans and changes nothing on it (hold true), or start it again (hold false), as the start card's Hold this account and the account card's Start again do. | { ads_account_id, hold: boolean } |
ads_account_billing_done | Write | Mark billing as set up on one ad account, so the Ads Agent stops asking for it and closes its Set up billing card. | { ads_account_id } |
ads_autopilot_set | Write | Switch Autopilot on or off for one ad account Fly runs (owner or admin, signed in). On needs the account's plan to carry Autopilot (the Autopilot plan or the Autopilot add-on; refused not_entitled with the Billing path to add it) and the last 14 days to have earned it (refused not_proven until Fly offers it on a card). With it on, Fly raises bids up to the ceiling, moves budget between campaigns inside the monthly budget, pauses losers, gives winners a fifth more a day and swaps in fresh ads on its own, tells each change after, and steps back by itself if the cost of a sign up doubles. Off any time. | { ads_account_id, on: true | false } |
ads_google_declaration_made | Write | Say the owner made Google's EU political advertising declaration on one Google ad account (owner or admin, signed in): Fly keeps the word, drops Google's refusal it kept, closes its declaration card as done, and the Google changes that failed on it are asked again on the next daily pass (a test's second ad among them); "Where things stand" stops naming the declaration. | { ads_account_id } |
ads_tracking_override | Write | How one ad account Fly runs is judged while its sign ups cannot be counted: run false holds its ads until they count (the owner's opt in: Fly pauses its running campaigns there on the next daily pass); run true takes the hold back, the default, so the ads run judged on clicks and visits and Fly switches back on what it paused. Owner or admin, signed in. | { ads_account_id, run: boolean } |
Example: The ad accounts
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_accounts_list \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. location and accounts: each with its id, platform, name, management (managed, advise or read_only), connection_status, currency and manager_url, the platform's own ads manager.
The strategy, the money and the aim
The monthly budget, each platform's cap, the goal, the offer and the area the agent works to, and the month's money: the budget against what was spent and where the month ends at this pace.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_strategy_get | Read | The Ads strategy: the monthly budget, each platform's cap and whether it is off, the lead service, the goal, the offer, the area, how often Fly checks on running ads (pace_minutes 30, 60, 180 or 360, null once a day, with pace_words) (WO-E: pace_words also says the pace this month where Fly's own work allowance steps it down, "every hour (every 3 hours this month, within Fly's work allowance)", while pace_minutes stays the owner's setting), whether campaigns go live on this test environment (live_here), and whether the customer list's sign ups and customers go back to the ad platforms (send_conversions on, off or null when never set) with the value of one customer (customer_value_minor, customer_value_currency); WO-F3: each ad account Fly runs with its Autopilot (autopilot: on, since, line "Autopilot on since Nov 08, 2026" or "Fly can run this on its own: see the card"; ads_autopilot_set switches it). ADS-AIM-1: beside the settings, the aim the Ads Agent works to (aim: cost_divisor and results_multiple, 3 and 3 unless the place has its own; cost_minor, a result at a third of what one cost before Fly, and results_month, three times as many a month, both null until the mark is known; currency; standing there, not_yet or unset for the month so far, null where the place has no aim; words, the line to say), read only. | {} |
ads_strategy_set | Write | Change the Ads strategy (owner or admin): monthly budget, platform caps, a platform off, lead service, goal, offer, area, how often Fly checks on running ads (pace_minutes; between the daily passes a light pass reads the running ads, tells what changed and finishes what waits on a platform); live_here lets campaigns go live on a test environment, Fly staff only, refused in production; send_conversions sends the customer list's sign ups, qualified leads and customers back to the ad platforms Fly runs (false stops it); customer_value_minor is the value of one customer, sent with each customer (null takes it off); inventory_feed_url is a vehicle dealer's own inventory feed address, passed on in the catalogue cards, and catalog_set_id the Meta product set the catalogue campaign shows while Fly cannot read the catalogues (ADS-SHOP-1; null takes either off); deploy runs the Ads Agent's pass now. Answers each change in words. | { edits: { monthly_minor?, caps?: { platform: minor | null }, off?: { platform: boolean }, focus?, goal?, offer?, radius_km?, areas?: string[], pace_minutes?: 30 | 60 | 180 | 360 | null, live_here?: boolean, send_conversions?: boolean, customer_value_minor?: number | null, inventory_feed_url?: string | null, catalog_set_id?: string | null }, deploy?: boolean } |
ads_money_get | Read | The month's money at the place, in the budget's currency (at the day's rate where an ad account spends in another): the monthly budget against what was spent, where the month ends at this pace and what is planned; a row an ad account with its cap and the room left, Fly's spend forecast for it, what was paid (to the platform, with its billing page, or from the Fly wallet), the ad leads and customers of the month with the cost of each and the payback where the value of a customer is set, and whether its numbers are in. This month by default, else one of the last 6. WO-E: fly_work is Fly's own cost of running the Ads Agent here this month (its AI, Treg and the supplier calls it keeps, never the ad spend) against $10 an ad account Fly runs: allowance_usd, spent_usd, room_usd, state (fine, tight from 70%, over, unknown where a cost source could not be read) and as_of; null for a past month or before Fly read it. Tight holds Fly's optional AI and checks running ads one step less often; over checks once a day and makes nothing new unless the owner asks on a card. | { month?: YYYY-MM } |
Example: The strategy
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_strategy_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. settings (the monthly budget, each platform's cap, the lead service, the goal, the offer, the area, the currency and how often Fly checks on running ads), aim, can_edit and deploy.
Who the ads are for, and how they look and sound
The confirmed audience and the agent's proposal, the brand the ads follow, the tone for each network, the audiences the agent builds from the site visitors and the customer list, and the owner's own lists (uploaded in the app with the consent declaration) whose people alone can be shown an ask's Facebook and Instagram ads.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_audience_get | Read | Who the ads are for: the confirmed audience (null until one is confirmed), each connected network with what it takes (interests, communities, conversations, industries, job functions, seniorities) or why it takes none, and what the owner's instructions set. | {} |
ads_audience_propose | Write | The Ads Agent's proposal of who the ads are for (AI, owner or admin): read from the business and the owner's instructions, every word resolved by each network's targeting search (a word none resolves is listed, never kept); only when none is confirmed, or with fresh. With q, network and kind, one targeting search for the owner's own additions. | { fresh?: boolean } | { q, network: metaads | redditads | linkedinads | pinterestads | xads, kind: interests | communities | conversation_keywords | industries | job_functions | seniorities } |
ads_audience_set | Write | Confirm who the ads are for (owner or admin): the whole audience (a proposal's, or the current one), or edits laid over the confirmed one. New campaigns take it, and the Ads Agent gives it to the running Meta and Reddit ad sets that carry none. | { audience?: { words, buyers, interests, age_min, age_max, gender, languages, networks: { platform: { targeting, own? } }, accounts? }, edits?: { words?, buyers?, interests?, age_min?, age_max?, gender?, languages?, networks?: { platform: { targeting?, own? } | null }, accounts?: { id: { platform, targeting?, own? } | null } } } |
ads_brand_get | Read | The brand the ads follow at the place: colours, fonts, when the logo shows, the tone, the lines every ad says and never says, what no picture shows, the languages. | {} |
ads_brand_set | Write | Set the brand the ads follow (owner or admin, signed in), or take it off with null: colours as hex codes (4 at most), fonts (3), logo_use always, never or when_room, tone words (5), must_say lines (5), never_say (10), banned_imagery (10), languages as codes (5). New ads follow it and the running ones are checked against what they must and never say. | { brand: { colours?: string[], fonts?: string[], logo_use?: always | never | when_room, tone?: string[], must_say?: string[], never_say?: string[], banned_imagery?: string[], languages?: string[] } | null } |
ads_voice_get | Read | How the place's ads sound: one tone for all networks and, for each network with an ad account connected, its own tone or the same as all, and its native touches (each with its line and the network's published page it rests on) and whether each is on. A tone has three axes, each one of three: register conversational, neutral or formal; humour playful, neutral or straightforward; attitude cheeky, neutral or respectful. Neutral with no touch changes nothing. The touches are not proven to lift results; where Fly tests two ads, one carries the voice and one stays neutral. | {} |
ads_voice_set | Write | Set how the place's ads sound (owner or admin, signed in), for all networks or one ("make my Reddit ads more conversational": network redditads, tone register conversational). tone sets any of register, humour and attitude; touches replaces a network's touches by key (ads_voice_get lists them); same_as_all puts a network back on the all networks tone; reset takes a network back to the all networks tone with no touches, or all networks back to neutral (each network's own tone stays). The owner's instructions for ads always come first. The next ads Fly writes on that network sound this way. | { network: all | metaads | googleads | openaiads | linkedinads | xads | pinterestads | redditads | tiktokads, tone?: { register?: conversational | neutral | formal, humour?: playful | neutral | straightforward, attitude?: cheeky | neutral | respectful }, touches?: string[], same_as_all?: boolean, reset?: boolean } |
ads_agent_audiences_list | Read | The audiences the Ads Agent built at the place from the site visitors and the CRM (site visitors, customers, leads, people like the customers), each with its network, people, last refresh, whether it holds the least its network needs and what it is used for (customers left out, the lookalike's seed, the X campaigns' list, the come back campaign), and the switch that builds them. | {} |
ads_audiences_setting_set | Write | Switch "Build audiences from your customers and site visitors" on or off at the place (owner or admin, signed in), and whether the ad leads get a list of their own. Off keeps the lists made and sends nobody more. | { on: boolean, include_leads?: boolean } |
ads_lists_read | Read | The owner's own lists at the place (people who gave the business their details, uploaded in the app): each list's name, where its people came from, status (draft under Meta's least of about 100 people, ready, refused, deleting) and why, the rows uploaded, the people kept and the rows left out by reason, and its audience on each Facebook and Instagram ad account (status, people Meta matched, refused with the next step). Counts only, never a person. | {} |
ads_list_remove_people | Write | Take people off one of the owner's lists (owner or admin, signed in): off Fly's list at once, off Meta on the next pass. rows are the people by email or phone, 5,000 at most. | { list_id: string, rows: [{ email?: string, phone?: string }] } |
ads_list_delete | Write | Delete one of the owner's lists (owner or admin, signed in): nothing of it on Meta yet, it goes at once; else Fly deletes the audience on Meta on its next pass and then the list. An open ask aimed at it goes back to everyone the ad aims at. | { list_id: string } |
ads_list_retry | Write | Try a list again on Meta after its ad account's admin accepted Meta's Custom Audience terms (owner or admin, signed in): the refusal is cleared and the next pass tries again now. | { list_id: string } |
ads_request_audience_set | Write | Set who sees an open ask card's Facebook and Instagram ads (owner or admin, signed in): only the people on one of the place's ready lists (ads_lists_read), or null for everyone the ad aims at. A list not on the card's ad account yet keeps that ad waiting until it is. Before Create campaigns only. | { action_id: string, list_id: string | null } |
Example: Who the ads are for
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_audience_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. networks (each connected network with what it takes), current (the confirmed audience, null until one is confirmed), proposal and instructions.
Instructions and rules
The owner's standing instructions for the Ads Agent, read by the agent before they are saved, and the owner's own rules, which the agent applies first on every daily pass.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_instructions_get | Read | The owner's standing instructions for the Ads Agent. | {} |
ads_instruction_read | Write | How Fly reads an instruction before it is saved (AI, nothing saved); hand its read.understood to ads_instruction_save. | { instruction } |
ads_instruction_save | Write | Save an instruction for the Ads Agent (id to change one). | { instruction, id?, understood?, every_place?: boolean } |
ads_instruction_set | Write | Pause or resume an instruction. | { id, active: boolean } |
ads_instruction_delete | Write | Delete an instruction. | { id } |
ads_rules_list | Read | The owner's own rules for the Ads Agent at the place (at most 10), each in words, with what a rule may watch and do and the place's money for a new one. The agent applies them first on every daily pass, before its own checks. | {} |
ads_rules_set | Write | Add, take off or replace the owner's rules for the Ads Agent (owner or admin, signed in): words reads one rule said plainly ("pause a campaign when a result costs over Rs 500 in 7 days", "tell me when a campaign spends over 2,000 a day", "lower the daily budget to Rs 1,000 when under 0.5% click"), or add takes it as fields. A rule watches a result's cost, a day's spend, the click rate or spend with no result over 1 to 30 days, and pauses the campaign, tells the owner or lowers its daily budget. | { words?: string } | { add?: { when: cost_per_result_over | daily_spend_over | ctr_under | no_results_after_spend, value_minor? (money, minor units), value? (ctr_under: percent), currency?, window_days?: 1..30, then: pause | tell | lower_daily_to, to_minor? } } | { remove?: rule id } | { rules?: rule[] } |
Example: The standing instructions
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_instructions_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. instructions and max, the most the place may keep.
Read the campaigns
Every campaign of the place's ad accounts with its numbers for a window, one campaign whole, the ad sets of an account, the Insights by part and an account's change history. Each account says how fresh its numbers are: stale and none are not known, never zero.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_campaigns_list | Read | Every campaign of the place's ad accounts (every mode) with its status, switch, budget and the window's spend, impressions, clicks, CTR, CPC, leads and conversions; each account says how fresh its numbers are (numbers_as_of, numbers_state: fresh, stale or none; stale and none are not known, never zero). | { ads_account_id?, from?: YYYY-MM-DD, to?: YYYY-MM-DD } |
ads_campaign_get | Read | One campaign as its ad account reads it now, led by its budget type (budget_type: daily, lifetime, or not reported), a lifetime budget's total (total_budget_minor, with currency) and its last day (last_day as Mon dd, yyyy in the account's zone and end_date, or last_day not reported where the platform gives none: ChatGPT gives none, its last day is Fly's own record, moved with ads_campaign_edit end_date); then its switch, budget, ad sets and ads with their words, a Google Search campaign's Bids (bidding), and what the owner may change on that platform. A ChatGPT, Meta, TikTok, X or Reddit bid is the ad set's: ads_level_ad_sets_get. | { ads_account_id, campaign_id } |
ads_level_ad_sets_get | Read | An ad account's ad sets (Google, Reddit, TikTok and ChatGPT ad groups, Meta ad sets, X line items, LinkedIn campaigns) on every platform: status, budget, start and end dates, bid, and each one's audiences (interests, communities, keywords, job functions, custom audiences, ages, genders, languages) and places, as the platform last reported them. | { ads_account_id, campaign_id? } |
ads_insights_get | Read | The Ads Agent's Insights for one part: performance (campaigns, ads, ad sets and day rows), keywords, competitors, decisions or sources. | { part: performance | keywords | competitors | decisions | sources, from?, to?, ads_account_id? } |
ads_level_history_get | Read | An ad account's change history: the owner's changes, the campaigns the owner made and what Fly did itself on it, newest first, at most 100 lines over a range of up to 92 days (the last 30 by default). | { ads_account_id, from?: YYYY-MM-DD, to?: YYYY-MM-DD } |
Example: Every campaign for a window
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_campaigns_list \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"from":"2026-11-01","to":"2026-11-09"}'The answer. location, window and accounts: each with its account, currency, totals and campaigns (status, switch, budget, spend, impressions, clicks, CTR, CPC, leads and conversions).
Ask for new campaigns
Ask the Ads Agent for campaigns about one thing: it writes the words and pictures and answers with one card to check, and nothing is made or spent until the owner says so on the card. Read what an ask may be about first with ads_request_options.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_request_options | Read | What a campaign ask to the Ads Agent may be about (services, products, running offers), each ad account Fly runs with its objectives, what each needs, its least daily budget and what holds it back. | {} |
ads_request_create | Write | Ask the Ads Agent for campaigns about one thing on the ad accounts picked: it writes the words and pictures and answers with one card to check; nothing is made or spent until the owner says so on the card. | { request: { request_id?, subject: { kind: service | product | offer | new, ref, name, words, price }, campaign: { goal: traffic | calls | awareness | signups | leads (signups and leads map to each platform's own objective: Meta and ChatGPT conversions, Meta's enquiry form, Google visits bid by its tracking; the New campaign flow starts on the strategy's goal), name, end_date, area: { kind: pin | country, radius_km? }, segment? (who the ads are for, 2 to 40 letters, like Salons; the Ads review board filters by it), platforms: [{ ads_account_id, objective, daily_minor | lifetime_minor, extras?, format?, ad? }], ad: { link_url, headline?, body?, button?, image_url?, google?: { headlines, descriptions, keywords } } } }. WO-A A3: the shared ad, or a platform's own ad, may carry the owner's headline (up to 40 letters), body, button (Learn more | Book now | Contact us | Order now | Shop now | Sign up | Get offer | Get directions), an https image_url and Google's headlines, descriptions and keywords; Fly writes and draws what is left out |
ads_requests_list | Read | The place's campaign asks to the Ads Agent with their state (waiting, making, made, failed), their card, its previews per platform and the campaigns made. | { open_only?: boolean } |
ads_request_edit | Write | Change an ask's card before anything is made: the words, page, button and budget per platform, the last day, and who the ads are for (segment; null clears it). | { action_id, platforms?: [{ ads_account_id, headline?, body?, button?, link_url?, daily_minor?, lifetime_minor?, google? }], end_date?, segment? } |
ads_request_create_step | Write | Answer an ask's card: create makes the campaigns paused, live switches them on (production only; the test environment keeps them paused), leave keeps them paused and closes the card. | { action_id, step: create | live | leave } |
ads_proposal_approve | Write | Approve a campaign proposal: the owner or an admin, or the business's client while the agency lets them (Your client's approvals on the strategy). Fly sets the campaign up paused; switching it on stays the agency's, so a client's yes never spends. | { action_id: string } |
ads_creative_look | Write | Ask for another look of an ad on a proposed campaign or new creative card. On a campaign ask's card (ads_owner_request) it answers request_card: ask again with the picture wanted as the image. | { action_id, ad?: first | second } |
ads_creative_words | Write | Change the words of an ad on a proposed campaign or new creative card. On a campaign ask's card the words change with ads_request_edit. | { action_id, ad?: first | second, headline, support? } |
Example: What an ask may be about
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_request_options \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. The services, products and running offers an ask may be about, and each ad account Fly runs with its objectives, what each needs and its least daily budget.
Change, pause and run campaigns
Pause or run campaigns and ad sets on any account, whatever its mode: that is the owner acting. Change a campaign, an ad set's budget or bid, the days and hours ads show, and a Google campaign's places.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_campaigns_status_set | Write | Pause or run campaigns on one ad account, all or the ids given, and ad sets by id; the owner's own action, so it works on every mode. With no ids a pause takes every campaign switched on; a run always names its campaigns or ad sets. A campaign run brings its ad sets and ads still paused along. | { ads_account_id, status: paused | active, campaign_ids?: string[], adset_ids?: string[] } |
ads_campaign_edit | Write | Change one campaign on an ad account Fly runs: its switch, name, daily budgets, a ChatGPT campaign's total (budgets [{ target: campaign, id, lifetime_minor }] on a campaign that runs on a total: daily_minor there answers lifetime_budget, since Fly never turns a total into a daily budget and ChatGPT never turns a daily one back; a raised total on a run whose last day on Fly's record is past or within a day answers a note naming that day, so send a new end_date with it), the last day (end_date YYYY-MM-DD, today or later in the account's zone: Meta's ad sets end on it; ChatGPT keeps no last day of its own, so there it is Fly's own record, nothing is sent to ChatGPT and Fly pauses the run once that day is over, said in notes), its ads' words, page, picture and switch (a Meta ad whose creative Meta keeps whole, such as one with text options, gets a new ad in the same ad set with its words and button and the change, the old ad paused: the result carries replaced { old_ad_id, new_ad_id }; not a new ad on the plan), and on Google Search its Bids (as many clicks with the most a click, or as many results), held to the platform's rules and floor. No other bid: a ChatGPT, Meta, TikTok, X or Reddit bid is the ad set's, set with ads_level_ad_set_change (action bid, cap_minor). A change it does not take answers nothing_changed with where that lives, and nothing is changed. | { ads_account_id, campaign_id, changes: { status?: active | paused, name?, budgets?: [{ target: campaign | adset, id, daily_minor } | { target: campaign, id, lifetime_minor }], end_date?, ads?: [{ id, status?, headline?, body?, button?, link_url?, image_url? }], bidding?: { strategy: max_clicks | max_conversions, cpc_cap_minor? } } } |
ads_level_ad_set_change | Write | Pause or run one ad set (the owner's own switch, on every mode), or set its daily budget or its bid, the most it pays (an ad account Fly runs; a bid on Facebook and Instagram, TikTok, ChatGPT, X and Reddit), owner or admin. ChatGPT's bid lives here, on each ad group (its id from ads_level_ad_sets_get), never on the campaign. An Activity line says so. | { ads_account_id, ad_set_id, action: "pause" | "run" | "budget" | "bid", daily_minor? (minor units), cap_minor? (the bid, minor units), campaign_id?, campaign_name? } |
ads_level_schedule_get | Read | The days and hours ads show: a Google campaign's windows (with include_performance, its impressions, clicks, cost and conversions by day of week and by hour over the last 30 days, in the account's time zone), or a Meta account's ad sets' whole hours. Other platforms take only start and end dates and answer unsupported. | { ads_account_id, campaign_id? (Google), ad_set_id? (Meta), include_performance?: boolean } |
ads_level_schedule_set | Write | Set the days and hours ads show on an ad account Fly runs (owner or admin): a Google campaign's windows in quarter hours, at most 6 a day, or clear: true for any hour of any day; a Meta ad set's whole hours (Meta runs them on a lifetime budget only; an empty list takes them off). Other platforms take none. A REPLACE: windows left out stop showing. | { ads_account_id, campaign_id? (Google), ad_set_id? (Meta), schedule?: [{ dayOfWeek: "MONDAY".."SUNDAY", startHour, startMinute?, endHour, endMinute? }], clear?: boolean, campaign_name? } |
ads_level_targeting_get | Read | A Google campaign's places (with their names and kinds), the places it leaves out, its languages and devices, and whether it reaches people in the places or also people searching for them. | { ads_account_id, campaign_id } |
ads_level_location_change | Write | Change a Google campaign's places on an ad account Fly runs (owner or admin): the full set of places it shows in (never none), the places it leaves out, or who they reach (presence: people in them; presence_or_interest: also people searching for them). Each list replaces that list. | { ads_account_id, campaign_id, locations?: [{ type, code, id }], excluded_locations?: [{ type, code, id }], reach?: "presence" | "presence_or_interest", campaign_name? } |
Example: Pause one campaign
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_campaigns_status_set \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pause-1234567890-1" \
-d '{"ads_account_id":"6b1e9d4c-3a7f-4c2b-8e5d-1f9a3c7b2e60","status":"paused","campaign_ids":["1234567890"]}'The answer. requested, results (each campaign with ok, changed, status and a line), the counts changed, failed and already, and a line that sums it up.
Google Search: ad groups, keywords, lines and assets
A Google Search campaign's ad groups, keywords, negative keywords, ad lines, sitelinks, callouts and snippets, read live from Google and changed on an account Fly runs; a Performance Max campaign's asset groups; and Google's own suggestions.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_level_ad_groups_get | Read | A Google Search campaign's ad groups, read live from Google: each with its ads, and each ad's headlines and descriptions (with any pin), the pages it opens, and Google's verdict on it (approval, review state and the policy topics Google names). can_change says whether you may change them. | { ads_account_id, campaign_id } |
ads_level_ad_group_add | Write | Make a new ad group for one product in a Google Search campaign on an ad account Fly runs (owner or admin): its name, its keywords (phrase match unless one is marked exact: { text, match: exact } or the search in [square brackets]), the page its ads open (a path on the site the campaign's ads open, or its https address there) and any headlines or descriptions you want; Fly writes the lines you leave out from the campaign's own ads and runs its ad checks, and says what they changed. Refused in words when the campaign is not Google Search, the page does not open, or the plan's ad groups on the account are in use. | { ads_account_id, campaign_id, name, keywords: Array<string | { text, match: phrase | exact }>, page, headlines?: string[], descriptions?: string[] } |
ads_level_ad_lines_set | Write | Change a Google Search ad's headlines (10 to 15 of up to 30 letters) and descriptions (4 of up to 90) in place on an ad account Fly runs (owner or admin). Fly's ad checks run first (distinct lines, the ad group's keywords, one keyword insertion) and say what they changed; check_only answers the checked lines without sending. Google reviews the changed ad again. | { ads_account_id, campaign_id, ad_id, headlines: string[], descriptions: string[], check_only?: boolean } |
ads_level_keywords_get | Read | A Google Search campaign's keywords (or one ad group's) as Google lists them: match type, status, Quality Score and its parts, and the last 30 days' impressions, clicks, cost and conversions. Google lists a new keyword within a day. | { ads_account_id, campaign_id, ad_set_id? } |
ads_level_keyword_change | Write | Change a Google Search campaign's keywords on an ad account Fly runs (owner or admin): add up to 20 to one of its ad groups as phrase or exact match (no claims your ads never make), pause, switch back on or remove one by its id from ads_level_keywords_get, or change its match type to phrase or exact (ADS-SEARCH-2: Google adds it again with the new match and the old one is removed). | { ads_account_id, campaign_id, campaign_name?, action: add | pause | run | remove | match, ad_set_id? (add), keywords?: [{ text, match: phrase | exact }] (add), keyword_id? (pause, run, remove, match), match?: phrase | exact (match) } |
ads_level_negatives_get | Read | A Google Search campaign's negative keywords at the campaign level, read live from Google: each search the campaign never shows on, with its match type (exact, phrase or broad), whoever set it, Fly or you in Google Ads. can_change says whether you may change them. | { ads_account_id, campaign_id } |
ads_level_negatives_change | Write | Keep searches out of a Google Search campaign, or let them back in, at the campaign level on an ad account Fly runs (owner or admin): add or remove negative keywords as exact, phrase or broad match. Fly reads Google's list first and keeps every negative already there; only the ones named change. Keeping a search out spends nothing. | { ads_account_id, campaign_id, campaign_name?, action: add | remove, keywords: [{ text, match: exact | phrase | broad }] (remove: match? takes out every match of the words when left out) } |
ads_level_assets_get | Read | Every asset Google lists for a Google Search campaign, read live: its own, each ad group's and the account's sitelinks (words, two lines, page and whether the page opens now), callouts, structured snippets and pictures; one row each with its type, level, Google's status where Google reports one, who added it (Fly or you) and asset, the id a change names; unread names a part Google did not give. instructions are the place's active Ads instructions. | { ads_account_id, campaign_id } |
ads_level_asset_change | Write | Change a Google Search campaign's sitelinks, callouts or snippet on an ad account Fly runs (owner or admin): add (links two at a time, each page must open), change or remove one by its asset id from ads_level_assets_get. A changed asset changes everywhere Google uses it. | { ads_account_id, campaign_id, campaign_name?, action: add | change | remove, kind: sitelink | callout | snippet | image (remove only), asset? (change, remove), sitelinks?: [{ text, url, line1, line2 }] (add, two or more), sitelink?: { text, url, line1, line2 } (change), callout?: string, snippet?: { header, values: string[] } } |
ads_level_asset_group_get | Read | A Google Performance Max campaign's asset groups, read live from Google: each group's headlines, long headline, descriptions, business name, wide and square pictures, logo and videos, with its ad strength and whether it serves. | { ads_account_id, campaign_id } |
ads_google_suggestion_answer | Write | On a card of Google's suggestions for an ad account Fly runs: apply one point on Google Ads (as Fly's take says), or say no so Google stops suggesting it. Never on a Fly recommends account. | { action_id, key, answer: apply | dismiss } |
Example: A campaign's keywords
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_level_keywords_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"ads_account_id":"6b1e9d4c-3a7f-4c2b-8e5d-1f9a3c7b2e60","campaign_id":"1234567890"}'The answer. The campaign's keywords as Google lists them: match type, status, Quality Score and its parts, and the last 30 days' impressions, clicks, cost and conversions.
A campaign's thread and its ad versions
The comments, the changes asked and the approvals on a campaign, and the kept versions of its ads.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_ad_comments_list | Read | One campaign's thread: the comments, the changes asked, the approvals and Fly's answers, oldest first, each with who wrote it ("Priya (agency)", "Owner", "Fly") and its day; a live campaign brings the talk on the cards that made it; and each ad's versions ("Version 2 of 3, Nov 03, 2026, after your comment"). campaign_id is the platform's campaign id, or card:<card id> for a proposal or a new creative still on its card. | { campaign_id: string } |
ads_ad_comment_add | Write | Post on a campaign's thread (signed in): a comment, or a change asked (kind change_request). A change on a card still waiting becomes its creative ask, so Fly redraws the ad on its next run and answers on the thread; on a running ad Fly draws a new version on a new ad's card. The client may comment, and ask for changes on a proposal, only while the agency lets them. | { campaign_id: string, kind: comment | change_request, body: string, ad_id?: string, design_key?: <card id>:first|second, ads_account_id?: string } |
ads_ad_version_use | Write | Put a kept version of an ad back (owner or admin, signed in): on a card still waiting at once; on a running Facebook and Instagram ad on an account Fly runs, Fly makes a new ad with it on its next run (held while the ad set is learning). | { action_id: string, which?: first | second, index: number } |
Example: A campaign's thread
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_ad_comments_list \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"campaign_id":"1234567890"}'The answer. thread, comments (each with who wrote it, its day, its kind and its words), versions of each ad, and what the caller may do: can_post, can_ask and can_use_versions.
Counting sign ups
How the agent knows a campaign brought a sign up: the Fly tag's site key and domains, the point and click rules for what counts on the site, the hook a server sends its sign ups to, and what was counted and sent back to the ad platforms.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_site_key_get | Read | The Fly tag's public site key for the place (made on the first ask by the owner or an admin), the domains it counts on, the page and time the tag was last seen, and the route that lets Fly judge the ads on sign ups (verified, by hook, tag or Fly site, since when). | {} |
ads_site_key_rotate | Write | Give the Fly tag a new site key (owner or admin, signed in); the pasted tag must then carry the new key. | {} |
ads_site_domains_set | Write | Set the owner's own domains the Fly tag counts on, beside the place's website (owner or admin, signed in; ten at most). | { domains: string[] } |
ads_conversion_rules_list | Read | The place's point and click rules: what counts on its own site (reaching a page, a form being sent, a click, an element appearing, the address after a history change), each with its name, the event the networks hear, its health (counting, new, quiet or gone: silent 7 days while the Fly tag sees the site), its real events of the last 30 days, those kept from every network (consent no, GPC), those waiting, and per network Fly runs: sent, and not sent with why (no click id, a network that takes none). Also where the Fly tag was last seen. | {} |
ads_conversion_rules_set | Write | Make a point and click rule, or change one by id (owner or admin, signed in): name Sign up, Purchase, Enquiry or the owner's own word (event sign_up, purchase or lead, else read from the name; an own word stays with Fly); kind page or route with match { o: exact | starts | contains, v: a path such as /thank-you, f?: the path a route comes from }, or kind form, click or element with match { s: a CSS selector, t?: the element's words }; page?: only on that path. Never a selector on what a person types. 20 rules a place. A changed kind, match or page counts as pointed at again. | { rule: { id?: string, name: string, event?: sign_up | purchase | lead, kind: page | form | click | element | route, match: object, page?: string, enabled?: boolean } } |
ads_conversion_rules_delete | Write | Delete one of the place's point and click rules (owner or admin, signed in); its events stay counted. | { rule_id: string } |
ads_setup_session_create | Write | Set up what counts: a one-time link (15 minutes, single use, this business only) that opens the owner's own site with Fly's set-up toolbar, to point at the thank-you page, a form, a button or a message (owner or admin, signed in). page: the https page to open on one of the business's domains (its website by default); rule_id: a rule to point at again. Give the owner open_url to open themselves; it works once the Fly tag is on that site (tag_seen). | { page?: string, rule_id?: string } |
ads_conversion_hook_get | Read | The place's hook a server sends its sign ups to (owner or admin, signed in): its address, when it was made and last used, and when it was revoked; never its secret. | {} |
ads_conversion_hook_create | Write | Make the place's hook a server sends its sign ups to (owner or admin, signed in), or make it again after a revoke; the answer carries the secret once, to give the developer. Refused with code exists while one is live. | {} |
ads_conversion_hook_rotate | Write | Give the place's sign ups hook a new secret (owner or admin, signed in); the old secret stops at once and the new one is in the answer once. | {} |
ads_conversion_hook_revoke | Write | Revoke the place's sign ups hook (owner or admin, signed in): its address stops taking sign ups and its secret is cleared. | {} |
ads_site_conversion_test | Write | Send a signed test sign up through the place's real hook (owner or admin, signed in) and answer what Fly recorded; a test proves the route, is never counted as a result and never sent to a network. | {} |
ads_conversions_list | Read | The last sign ups, purchases and leads Fly counted at the place from the site's server or the Fly tag: when, the page, the network, campaign and ad it came from and how Fly knew (fly_ad, utm or the click id), and each network it was sent to, or why not (consent, GPC, a test, no match key). | { limit?: number, from?: YYYY-MM-DD, to?: YYYY-MM-DD } |
ads_conversion_sends_list | Read | What the Ads Agent sent back to the ad platforms for a range (the last 30 days by default): the sign ups, qualified leads and customers from the customer list by platform, the failures with their reason, the ones taken back on Google, Meta's match quality with what is missing, Google's import actions, and whether sending is on (send_conversions on the strategy). | { from?: YYYY-MM-DD, to?: YYYY-MM-DD } |
Example: The Fly tag
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_site_key_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. The Fly tag's public site key, the domains it counts on, where and when the tag was last seen, and how Fly judges the ads on sign ups.
Google Analytics
A Google Ads account's Google Analytics, the steps Fly may set up itself, and what each network claims against what Analytics saw.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ga_ads_state | Read | A Google Ads account's Google Analytics: the business's one connection (shared with the Website Agent), whether Fly may set up sign up tracking itself, and the four steps (key event, link, import, auto-tagging) as the last pass saw them, with Google's help page for each. Recommended, never required. | { ads_account_id } |
ga_ads_connect | Write | Connect Google Analytics for the business (owner or admin, signed in): answers Google's consent address to open; the Website Agent uses the same connection. Answers already when the business has one. | { ads_account_id } |
ga_ads_setup | Write | Let Fly set up sign up tracking (owner or admin, signed in): where Google Analytics offers edit access, Fly marks the sign up event as a key event and links the Google Ads account, after one consent to widen the connection. Answers edit_not_offered with the steps while Google Analytics connects read only. | { ads_account_id, event?, property? } |
ga_ads_recheck | Write | Check a Google Ads account's Google Analytics again now, after the owner did a step: its key events and Google Ads links read through the business's one connection, the kept read and the open card brought up to date in place, what changed in one line. At most once every 5 minutes an account. | { ads_account_id } |
ads_attribution_get | Read | What each ad network claims against what Google Analytics saw from its paid visits, week by week over the last 28 complete days of each read: the results the network claims (only results on the site), the key events and sessions Analytics saw from its ads, the results Facebook and Instagram counted after a view with no click, the gap and whether the weekly email tells it (30% or more on a network claiming 10 or more), with the reading in words; and whether Google Analytics is connected. | { weeks?: 1..12 } |
Example: Claimed against seen, week by week
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_attribution_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"weeks":4}'The answer. weeks, newest first, each with its networks (the results each claims, the key events and sessions Analytics saw, the gap and a line), and analytics with whether it is connected.
Recommendations, tests and checks
The review cards of the accounts Fly recommends on, the agent's ad tests and region tests, and its hygiene checks.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_recommendations_list | Read | The Ads review cards of the ad accounts Fly reads and advises (Fly recommends): each point with why, steps and where. | { ads_account_id?, open_only?: boolean } |
ads_recommendation_item_set | Write | Answer one point of an Ads review card: done, or not now (later). | { action_id, key, state: done | later } |
ads_tests_list | Read | The Ads Agent's tests at the place: each Facebook and Instagram ad set whose two ads are judged against each other (running, decided or void), with each ad's views, clicks, spend and results since the test began, the days left to a decision (21 at most), the ad kept and the lift for a decided one, whether the owner's yes is still asked, and how a void one ended. | { status?: running | decided | void } |
ads_holdouts_list | Read | The region tests (geo holdouts) at the place, newest first: the campaign, the place paused for 14 days and the place kept running, asked, running, back or void, the days, and once back the leads each place brought before and during the pause with the reading in words. A test is asked on its own card in every mode, never started here. | {} |
ads_hygiene_get | Read | The Ads Agent's hygiene checks at the place: the open cards for spend running far ahead of the usual day, an ad account on hold and a Display or YouTube campaign to keep off sensitive content; last month's clicks Google filtered as invalid on each Google ad account; whether the site asks each visitor before its ad tags run (consent mode, by the place's country); and each ad account's regulated trade verification, asked or answered. | {} |
Example: The open review cards
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_recommendations_list \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"open_only":true}'The answer. recommendations, newest first, each card with its points: why, the steps and where.
Competitors
The competitors named for the Ads Agent, whose ads it reads in the public ad libraries, and its suggestions.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_competitors_list | Read | The competitors named for the Ads Agent at this place (rivals and the suggestions waiting), where each came from, and whether Suggest competitors can run today. | {} |
ads_competitor_add | Write | Name a competitor for the Ads Agent: it reads that company's ads in the Meta Ad Library, Google's Ads Transparency Center and the LinkedIn Ad Library. Read now may read again the same day. | { name, website? } |
ads_competitor_set | Write | Mark a named or suggested competitor as a rival or not a rival, or remove it. | { id, status: rival | not_rival | remove } |
ads_competitors_propose | Write | Suggest competitors for the Ads Agent from similar companies and Fly's read, kept as suggestions to answer; once a day per place, spends a data call and an AI call. | {} |
Example: The competitors
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_competitors_list \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. rivals, the competitors and the suggestions waiting, can_edit, and suggest: whether Suggest competitors can run today.
Notices and the weekly email
Whether the owner hears of every change to the ads, and the weekly ads email sent now.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_change_notices_get | Read | Whether the owner hears of every change to the place's campaigns and ads (Ads Settings, "Tell me about every change to my ads"): the bell at once and an email, at once when the ads stop, else at most one every 15 minutes. | {} |
ads_change_notices_set | Write | Switch "Tell me about every change to my ads" on or off at the place (owner or admin); off keeps the Activity lines only, no bell and no email. | { on: boolean } |
ads_weekly_send_now | Write | Send this week's ads email now: the week so far (Monday to yesterday, or the last 7 days on a Monday) goes to the owner on the next Ads pass, whatever the day or the hour, with the links to the Ads report and to everything the agent did. Signed in; the Ads Agent must be on at the place. | {} |
Example: Change notices
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ads_change_notices_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. on: whether the owner hears of every change.
More operations
Every other operation of this page, as the catalogue lists it.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ads_catalogue_get | Read | The place's catalogue ads: whether it sells from a catalogue (a shop with products, or a vehicle dealer), its product feed (the address the Fly site serves, or a dealer's own inventory feed), each Meta ad account's catalogues and product sets as Fly last read them with the set a catalogue campaign shows, whether Meta's catalogue permission is missing (Fly cannot read catalogues then, and uses the product set ID the owner typed), and the catalogue campaigns Fly made with their product set and format. | {} |
ads_review_angle_new | Write | New copies with an angle on an ask card: angle names the angle to attack (Fly scores it beside its own, keeps it with the card's angles and drafts it as a new ad beside the others in the same Meta ad set, saying where it ranks; a network that takes one ad an ask has its ad drawn from it, the old kept as a version), or angle_id drafts one of the card's angles not drafted yet (Draft this angle too). Each new ad counts as a new ad on the plan. Signed in, the owner or an admin. | { action_id: string, angle: string, ads_account_id?: string } | { action_id: string, angle_id: string, ads_account_id?: string } |
ads_review_angles_get | Read | The angles of an ask card (ads_owner_request): each with its angle line, takeaway, why it should convert, the proof it needs, its score 0 to 100 with the reason and the evidence of Fly's own numbers where they exist, highest first; each ad on the card with its angle (first, second and on, the ads in the same ad set); the angles not drafted; the refines asked with their answers; the campaign refine with its proposed edits. | { action_id: string } |
ads_review_feedback | Write | Leave feedback on one ad of an ask card: a comment on the card's thread (card:<action_id>), which the team and the agency see. Signed in. | { action_id: string, body: string, which?: first | second | v3 | v4, ads_account_id?: string } |
ads_review_list | Read | The Ads review board: the Ads Agent's answers to the owner's asks of the last 120 days, newest first, each with its state (To review, Made, paused, Live, Closed, Failed), segment, the ask's name, its time and its app address, and each network's ad (words, picture, page, budget, last day, campaign) with who the ask said it is shown to (area, countries, cities, radius, ages, gender, interests, languages; null where the ask recorded none); facets counts the ads by region, segment, age, gender, network and state. | {} |
ads_review_refine_ad | Write | Refine one ad of an ask card with the owner's words (3 to 600 letters): before anything is made, Fly draws its words and picture again on a pass that starts now, keeps its angle unless the words change it, keeps the old as a version and answers on the card (refine_asks) and the thread; once made, the change goes to the running ad as a new version on its own card. Four asks wait on a card at most. Signed in, the owner or an admin. | { action_id: string, words: string, which?: first | second | v3 | v4, ads_account_id?: string } |
ads_review_refine_campaign | Write | Refine an ask card's campaign: with words (who, where, how much or until when) Fly answers on the card with the concrete edits for a yes (campaign_refine: lines, spends_more), never applied unasked; answer yes applies them (before anything is made to the ask and its previews, each network held to the create's checks; after, the last day and the budgets through ads_campaign_edit), no leaves it as it is. Signed in, the owner or an admin. | { action_id: string, words: string } | { action_id: string, answer: yes | no } |