Skip to main content
A partner says a click never landed. An advertiser disputes a conversion. A pixel looks like it fired twice. This page is the route through the tools for each of those. The records themselves — clicks, conversions, transactions, orders — are read through the generic entity tools. Their full response shapes and listing filters are in Event response fields.

​
Start here

Clicks and transactions are identified by the 32-character transaction ID; conversions by the conversion ID.

​
Trace one transaction end to end

get_entity(type="transaction", …) is the fastest path from an ID to an answer, because it returns every layer of the chain at once:
Each collection is capped at 10 items. Compare <name>_total with <name>_returned to spot truncation; when conversions are truncated, conversions_note hands you the exact list_entities call to page through the rest.

​
Error codes worth knowing

Every click and conversion carries an error_code. 0 means accepted — it has no lookup row, so get_entity(type="click_error_code", id=0) returns INVALID_ARGUMENT. For any non-zero code, resolve it with get_entity(type="click_error_code", id=<code>) or get_entity(type="conversion_error_code", id=<code>). These are the ones you’ll meet most: For a breakdown by code rather than one record at a time, group a report on it: run_performance_report(dimensions="click_error_code") or conversion_error_code.

​
Counting by reason over time

“How many manually rejected conversions per day”, “yesterday’s proxy clicks”, “how many declines”: these are counts by reason code, and the route is always the same.
  1. Resolve the phrase to a code with list_entities(type="click_error_code") or type="conversion_error_code" (click codes and conversion codes are different tables; conversion-import errors are a third list).
  2. Count it with a report: run_performance_report(dimensions="date", filters="error_code:<code>"), or dimensions="affiliate" for who sent it, or dimensions="click_error_code" for the whole mix in one call.
  3. For the meaning, search_documentation on the two error-code reference guides.
Three readings to get right:
  • A grouped result with no row for a code means zero of that code in the window, never that the code does not exist. Say “0 proxy-blocked clicks yesterday”, not “there is no proxy reason”.
  • A negative count under an error_code filter is a data_warning, not a figure: the filter can exclude a click whose conversion is still aggregated. Re-run without the filter or group by the code.
  • Invalid clicks are part of gross clicks (gross_clicks = clicks + invalid_clicks); a “decline” event name on a conversion is not a rejected conversion.

​
Common investigations

“My click never registered.” Fetch the click. A non-zero error_code is the answer — resolve the number to its meaning with get_entity(type="click_error_code", id=<code>). Code 0 means accepted, and has no lookup row. If the click isn’t found at all, widen to search_activity(type="click") over the window with the partner’s affiliate_id and sub1 to confirm whether anything arrived. “This conversion shouldn’t have paid out.” Fetch the conversion and check attribution_method, click_timestamp against timestamp, and is_scrub. Then fetch the offer’s session_duration with get_offer to confirm the click was inside the attribution window. “The numbers don’t match the invoice.” Check list_entities(type="reporting_adjustment", filters={"from":…, "to":…}) first. Manual adjustments are applied on top of tracked data and are the usual explanation for a gap between a report and a bill. “A conversion is missing from my report.” Look for it on hold: list_entities(type="on_hold_conversion", filters={"affiliate_id": …}). Held conversions don’t count until the holding period ends. “Which store did this order come from?” get_entity(type="order", id=<store order id>) returns shopify_store_url, integration_id, and the transaction_id that links it back to the attribution chain.

​
Two things that will bite you

Identity fields are masked. session_user_ip and conversion_user_ip are abbreviated for conversions from GDPR countries; idfa, google_ad_id and android_id have trailing characters replaced; email is obfuscated (a*******@example.com). This matches the REST conversion export. Treat all of them as personal data.
Single-record lookups return slightly more than stream searches. get_entity resolves a few values that would be an N+1 across a 1,000-row stream: on clicks that’s offer_name, affiliate_name, advertiser_name and has_conversion; on conversions it’s error_message and campaign_id. Everything else is identical. If a field you expect is missing from a search_activity result, fetch the single record before concluding the data doesn’t exist.
The former get_click and get_conversion tools remain callable for backward compatibility but are deprecated and no longer listed — see Deprecated tools.

Event response fields

Every field on a click, conversion, transaction, and order, plus their listing filters.

Agentic Examples

Full agent traces, including diagnosing a blocked click end to end.