Connect Pinterest Ads
Tasks call the Pinterest Ads API through qbash.integrations.pinterest_ads. The connector reads ad accounts, campaigns, ad groups, ads, audiences, keywords and conversion tags. It pulls analytics and longer reports, sends conversion events, and updates status, budgets and bids.
It can't create campaigns, ad groups or ads, and it doesn't touch billing. For Pins and boards, use Connect Pinterest.
Check your ad account access
The connector acts as the Pinterest user who signs in, and reaches every ad account that user owns or was given through Business Access. Reports need the Owner, Admin, Analyst or Campaign Manager role on the ad account. Updates need a role that can edit campaigns in Ads Manager.
Add the credential in qbash
- Open Connectors → Pinterest Ads → Connect.
- Name the credential, for example after the ad account, and select Connect Pinterest Ads.
- Sign in to Pinterest in the popup and select Give access.
Pinterest asks for read and write access to ads and read access to the account. The credential stays connected as long as a task or chat uses it at least every 60 days.
Pull a report
Select the credential under your task's Tools → Integrations. Find the ad account ID with list_ad_accounts, then:
end = (datetime.now(timezone.utc) - timedelta(days=1)).date()
report = qbash.integrations.pinterest_ads.get_campaign_analytics(
ad_account_id="549755885175",
campaign_ids=["626735432189"],
start_date=(end - timedelta(days=6)).isoformat(),
end_date=end.isoformat(),
columns=["SPEND_IN_DOLLAR", "PAID_IMPRESSION", "TOTAL_CLICKTHROUGH", "TOTAL_CONVERSIONS"],
granularity="DAY",
)
qbash.output(report["rows"])
The analytics methods cover up to 90 days. For longer ranges, create_report starts a report of up to 186 days and returns a token. Call get_report with that token until it finishes, and it saves the report to qbash as a JSON or CSV file. See the SDK Reference for every method.
Change campaigns, ad groups and ads
update_campaigns, update_ad_groups and update_ads change up to 30 items per call:
- status:
ACTIVE,PAUSEDorARCHIVED - name, start time and end time
- budgets, bids and spend caps, in micro-currency where 1,000,000 is 1 unit of the ad account's currency
Changes reach live ads at once and can raise or stop spend. When Pinterest refuses some items, the call returns "status": "partial" with an error for each one.
Send conversion events
send_conversion_events sends up to 1,000 events to the ad account through Pinterest's Conversions API. qbash hashes emails, phone numbers and the other personal fields with SHA-256 before sending and keeps them out of the task log. Pass test=True to check a batch without recording it.
Seed test data
Create an ad account in Pinterest Ads Manager. The account itself needs no billing details. A campaign saved as a draft in Ads Manager shows up in list_campaigns with entity_statuses=["DRAFT"] and never spends, so it is a safe target for update tests.
Limits
- Reports and analytics return only days with recorded delivery.
get_metrics_ready_statesays whether a day's numbers are final. - Analytics take at most 250 campaign, ad group or ad IDs per call.
- Pinterest limits how many calls qbash's Pinterest app makes each day across all accounts. A call over the limit fails with a rate limit error until the limit resets.