Every tool the Propush MCP connector exposes, generated straight from the live registry.
Write operations are labeled, and destructive means the change cannot be undone; everything else is read-only.
get_sites read-onlyGet the list of all sites in your Propush account. Returns site ID, URL, verification status (1=Pending, 2=Verified), and a type field: site, landing, constructor, or null in any other case. Only verified (2) sites of type site or landing can take new zones (see create_onclick_zone); moderation approval is required for that too, and it is not reported here.
The id here is the site id get_zones reports as site_id, but it is NOT the site_id get_statistics reports or accepts — see get_statistics before filtering a report by site.
Paginated server-side, ordered by id. The response carries meta { page, page_size, total_items, total_pages, has_more }; page_size defaults to 100 and is capped at 500. To fetch everything, keep page_size fixed and walk page from 1 to total_pages.
Parameters
page — Page number (default: 1)page_size — Sites per page (default: 100, maximum: 500). Larger values are clamped to the maximum.get_zones read-onlyGet list of all zones (ad tags). Each zone has an ID (the number get_statistics reports and accepts as zone_id), title, site_id (the same id get_sites returns, and not the site_id get_statistics reports), direction_id (72=Push Notifications, 73=Traffic Back), active status, site_direction_id (the number get_statistics reports as affiliate_id) and postback_url ({url}, or null when no postback is set — the ground truth for the postback tools).
Paginated server-side, ordered by id. The response carries meta { page, page_size, total_items, total_pages, has_more }; page_size defaults to 100 and is capped at 500. To fetch everything, keep page_size fixed and walk page from 1 to total_pages. Prefer the site_id filter over walking many pages when you only need one site's zones.
Parameters
page — Page number (default: 1)page_size — Zones per page (default: 100, maximum: 500). Larger values are clamped to the maximum.site_id — Return only zones belonging to this sitecreate_onclick_zone destructiveCreate a new onclick (TrafficBack) zone under one of your sites. Returns the new zone's id, title, and creation timestamp. A created zone cannot be deleted afterwards.
The site must be a plain site or landing page (type 'site' or 'landing' in get_sites — constructor and other placements are refused with 400), owner-verified (user_verification_status 2) and approved by moderation. A site that is not verified, still under moderation or rejected gets a 403 whose hint names the reason, e.g. 'This site has not been verified yet. Please verify site ownership before creating zones.' Moderation status is not part of get_sites, so that hint is the only place it shows up; the site's state has to change before a retry can succeed.
Parameters
site_id — Publisher site IDtitle — Zone title (max 100 characters)get_constructors read-onlyList your Propush landing constructors. Each constructor has an id (the site id get_sites and get_zones report — the postback tools take it as site_id), human-friendly name, type (landing template, e.g. 'social-survey'), creation timestamp, onclickDomain (the domain its onclick zones are served from, or null when it has none) and its zones — each with id, title, zoneType (the zone's place in the landing, e.g. 'mainExit_currentTab'), direction, isActive, isArchived, postbackUrl ({id, url} or null when none is set) and serviceWorker (the push zone's service worker file as {domain, name, content}; null on other zones). Requires constructor access (see is_constructor_available from get_me).
Paginated server-side, ordered by id. The response carries meta { page, page_size, total_items, total_pages, has_more }; page_size defaults to 20 and is capped at 50. To fetch everything, keep page_size fixed and walk page from 1 to total_pages.
Parameters
page — Page number (default: 1)page_size — Constructors per page (default: 20, maximum: 50). Larger values are clamped to the maximum.get_constructor read-onlyGet a single Propush landing constructor by ID, in the shape get_constructors describes. Requires constructor access (see is_constructor_available from get_me).
Parameters
constructor_id — Constructor IDcreate_constructor destructiveCreate a Propush landing constructor from a landing template, together with every zone the template defines, and return it in the shape get_constructors describes. Each template has its own Landing Constructor doc (search_docs). A constructor cannot be deleted afterwards, and each one counts toward the account's constructor limit — once it is reached, new constructors are refused. Requires constructor access (see is_constructor_available from get_me).
Parameters
type — Landing template, e.g. 'social-survey'get_trending_geos read-onlyGet the latest published "trending GEOs" weekly digest for the Propush landing constructor — week-over-week impression-volume and CPM momentum by country. The figures cover landing-constructor traffic only. Returns metadata (slug, publishedAt) and a data payload. The data structure is digest-specific and is not covered by backward-compatibility guarantees — it may change without notice, so read the values as they come rather than relying on a fixed shape. Until a digest has been published the call fails with "No trending GEOs digest has been published yet." — digests are published periodically, so an immediate retry returns the same. Requires constructor access (see is_constructor_available from get_me).
No parameters
get_balance read-onlyGet the current Propush account balance in USD.
No parameters
get_me read-onlyGet the authenticated Propush account's id, API access level, and feature availability. access_level is one of '' (no API access), 'base' (standard access) or 'extended' (adds grouping by request_var and multi-field grouping in get_statistics). is_constructor_available is true when the account may use the Propush landing-constructor tools (get_constructors, get_constructor, create_constructor) and the trending-GEOs digest (get_trending_geos); when false those tools return an access error. is_ai_landing_available is true when the account can create AI-built landings in the Propush dashboard.
No parameters
get_statistics read-onlyGet Propush statistics for your zones and sites with grouping and filtering.
Every row of the regular report carries these metrics: prerequests, impressions, subscriptions, money (USD earnings), push_already_subscribed, push_first_impressions, push_unsubscriptions.
Rows also carry whatever you grouped by, and some of those fields are raw IDs. Look them up before putting them in a report:
- os_id arrives with os next to it, the OS name (e.g. 'android') — use the name. It is null when the OS was not detected (os_id 0), and that traffic cannot be filtered at all. The os filter takes names, not IDs; get_os lists them.
- country_id is a bare number. get_countries turns it into a country name and ISO code. Filtering does not need that lookup: the countries filter takes ISO codes directly.
- affiliate_id identifies a site-and-direction pair. The same number appears as site_direction_id in get_zones. It has no filter of its own, so narrow with zone_ids and directions instead.
- zone_id is the id get_zones returns — take the zone's title, and the site it belongs to, from there.
- site_id is NOT the id get_sites and get_zones report: statistics numbers sites in a space of its own, so the two never match, and passing a get_sites id as site_ids is refused with "The selected choice is invalid." It has no dictionary of its own — it resolves to a nameable site only through the zones: group by zone_id and read each zone's site_id and title from get_zones (grouping by [site_id, zone_id] gives the pairing directly, but multi-field grouping needs the 'extended' access level). That roll-up is also how to report per site; to narrow to one site you already know, pass that site's zones as zone_ids. site_ids only accepts values that came out of a site_id grouping.
tz works only when date_from is within the last 7 days. On an older range the API rejects the whole call with "Time zone is available only in the weekly period." That message is about the date range, not the offset, so a different offset or a retry will not help — either leave tz out (dates are then EST) or move date_from closer to today.
Grouping by subscription_date switches to a different report: subscriber lifetime value per subscription day. It has to be the only group_by field and cannot be combined with tz or directions — that report has no room for them, so such a call is refused. date_from/date_to then pick subscription days, not earning days. Each row is one subscription day with subscription_date, subscriptions, money_0-1, money_2-7, money_8-14, money_15-30 and money_30+ (what that day's subscribers earned 0–1, 2–7, 8–14, 15–30 and 30+ days after subscribing; null when nothing), the matching money_percent_* shares of subscriptions_money (the sum of those five), trafficback_money, and total_money (subscriptions_money plus trafficback_money). None of the regular metrics are there — no impressions, no money. zone_ids, site_ids, countries, os and request_vars narrow it as usual.
Examples:
- Daily earnings: { date_from: "2024-01-01", date_to: "2024-01-07", group_by: ["date_time"] }
- By country: { ..., group_by: ["country_id"] }
- Specific zones: { ..., group_by: ["zone_id"], zone_ids: [123, 456] }
The response is { result: [ ...rows ], meta: { total_items, total_pages, page_size, page } }. page_size is capped at 200 rows so that one page fits the client's result-size limit — check meta for the window that was actually applied. For a report that spans pages, keep page_size as it is and walk page from 1 to meta.total_pages, though narrowing the dates, the filters or group_by usually beats paging through everything.
Parameters
date_from — Date FROM in YYYY-MM-DD format (EST timezone)date_to — Date TO in YYYY-MM-DD format (EST timezone)group_by — Fields to group by. Valid values: date_time | zone_id | site_id | country_id | os_id | affiliate_id | request_var | subscription_date. Grouping by 'request_var' or by multiple fields requires the 'extended' API access level (check via get_me). 'subscription_date' switches to the subscriber lifetime-value report and has to be the only field.zone_ids — Filter by zone IDssite_ids — Filter by the `site_id` values a `site_id` grouping returned. These are NOT the ids get_sites and get_zones report — one of those is refused with "The selected choice is invalid." To narrow to a site you already know, filter by its zones with `zone_ids` instead.countries — 2-letter ISO 3166 Alpha-2 country codes in any case, e.g. ['us', 'in']directions — Direction filter. 'onclick' for TrafficBack, 'nativeads' for Push Notifications. Not available with a subscription_date grouping.request_vars — Filter by source ID stringsos — Filter by OS name, e.g. ['android', 'ios']. These are the names get_os lists and grouped rows carry in `os`. Traffic with an undetected OS has no name, so it cannot be filtered. An unknown name comes back with the list of valid ones.tz — Whole-hour UTC offset written as '+HH00' or '-HH00' (e.g. '+0300'), from '-1200' to '+1400'. Half-hour offsets like '+0530' and named zones like 'America/New_York' do not work. Only accepted when `date_from` is within the last 7 days; on an older range the API rejects the whole call, so leave it out there. Without it, dates are EST.page — Page number (default: 1)page_size — Rows per page (default: 100, maximum: 200). Larger values are clamped to the maximum.get_countries read-onlyGet every available country with its numeric ID and ISO 3166 Alpha-2 code. Use it to read the country_id field of get_statistics rows grouped by country — those rows carry the numeric ID only, so this list is the only way to name them. Filtering does not need this tool: get_statistics takes ISO codes directly.
No parameters
get_os read-onlyGet every operating system that statistics can be grouped or filtered by: numeric ID, value (the name get_statistics rows carry in os and its os filter accepts, e.g. 'android') and title (display form, e.g. 'Android'). Requires a Propush account. Filtering does not need this tool: get_statistics takes the names directly — use it to see what names exist.
No parameters
set_zone_postback destructiveCreate or replace the postback URL for one zone. The URL can carry the postback macros, substituted at request time: {ymid} (click id), {request_var} (source id), {geo} (country), {sub_cnt} (user rank) — the 'Instructions for postback propush.me' help article (search_docs) explains them. Only onclick (TrafficBack) zones are supported.
Parameters
site_id — Publisher site IDzone_id — Zone IDurl — Postback URL, e.g. 'https://example.com?ymid={ymid}'delete_zone_postback destructiveDelete the postback URL for one zone. Only onclick (TrafficBack) zones are supported. A bare 403 "Access Denied." means the zone has no postback to delete (check its postback_url in get_zones first), the zone is not on that site, or the site is not currently approved for new zones (not verified, under moderation or rejected).
Parameters
site_id — Publisher site IDzone_id — Zone IDbulk_set_zones_postback destructiveCreate or replace the same postback URL on multiple zones at once. All-or-nothing: if any zone fails validation, no changes are made. The URL takes the same macros as set_zone_postback. Only onclick (TrafficBack) zones are supported.
Parameters
site_id — Publisher site IDzone_ids — Zone IDs to assign the postback URL tourl — Postback URL to assign to all listed zonesbulk_delete_zones_postback destructiveDelete postback URLs for multiple zones in one call. All-or-nothing: every zone must already have a postback — if any does not, the whole request is refused with a bare 403 "Access Denied." and nothing is deleted (check postback_url in get_zones first). A zone id that does not exist is refused with 400 "Zones not found: …". Only onclick (TrafficBack) zones are supported.
Parameters
site_id — Publisher site IDzone_ids — Zone IDs whose postback URL should be deletedsearch_docs read-onlySearch Propush documentation (Landing Constructor docs + Help Center articles). Returns ranked title+snippet hits with the resource URI of each match — use the read_doc tool with a URI to fetch full Markdown. Landing Constructor docs are searched only for accounts with constructor access (see is_constructor_available from get_me); other accounts get Help Center hits only.
Parameters
query — Keywords or phrase to search for, e.g. 'postback macros', 'trafficback'limit — Max number of results (default 10)read_doc read-onlyFetch the full Markdown of a Propush documentation entry by URI (the URIs returned in search_docs.hits[].uri). Landing Constructor entries require constructor access (see get_me); without it the call returns an access error.
Parameters
uri — A propush://docs/<source>/<slug> URI from search_docs.hits[].uri