Skip to navigation
MCPs and AgentsUse

Tool reference

What each Pixalate MCP tool does, what it accepts and what it returns.

You don’t have to call these tools by name. Ask your assistant in plain language and it picks the tool and fills in the inputs. The names and inputs are here so you can be specific when you want to, and so you can read what came back.

Which tools you see depends on your account. If a tool is missing, see Access and limits.

ToolWhat it does
analytics_describeLists the analytics reports your account can run, or the columns of one report.
analytics_queryRuns an analytics report for a date range, inline or as a CSV export.
analytics_statusCollects the result of a report that was still running.
mrt_enrichment_queryReturns Pixalate data widgets for mobile apps, CTV apps or web domains.

Earlier versions of this documentation used tool names that started with pix_, such as pix_analytics_query. Use the names on this page.

All tools are read-only. Every tool also takes an intent field, a sentence on why the call is being made. Your assistant fills it in.

Analytics

The analytics tools run Pixalate Analytics reports for your account. Start with analytics_describe: report and column availability differs between accounts, so it’s the source of truth for what you can run.

“What Pixalate reports can I run?”

“What columns are available on that report?”

“Run that report for September 1 to 30, sorted by IVT rate, and show the top 10.”

analytics_describe

Discovers the reports and columns available to your account.

InputRequiredDescription
report_idNoLeave out to list your reports. Pass a report ID for that report’s columns. Pass custom for the columns you can use in a custom report.

Without report_id, you get reports: each report’s report_id, title and group. With a report_id, you get:

  • columns: each column your account can use on that report, with its label, format, whether it’s a metric (isMetric) and a tooltip.
  • export_supported: whether the report can be exported as a CSV.
  • max_dimensions: the most dimensions the report accepts, or null when there’s no cap.

If a report isn’t available to your account, the response has an error instead.

analytics_query

Runs a named report, or a custom column selection, for an inclusive date range.

InputRequiredDescription
report_idYesA report ID from analytics_describe, or custom for your own column selection.
date_fromYesStart date, YYYY-MM-DD, inclusive.
date_toYesEnd date, YYYY-MM-DD, inclusive. The range can be at most 60 days.
dimensionsFor customDimension columns. Optional for a named report, where it overrides the report’s defaults.
metricsFor customMetric columns. Optional for a named report, where it overrides the report’s defaults.
filtersNoA list of conditions. Each has a field, an operator (=, !=, CONTAINS, IN or NOT IN), a list of values, and an optional join (OR, the default, or AND) for combining several values with =, != or CONTAINS. CONTAINS is a case-insensitive substring match.
group_byNoDimension columns to group by.
order_byNoColumn to sort by. Defaults to the report’s own sort.
order_dirNoDESC (default) or ASC.
startNoRow offset for paging. Default 0.
limitNoRows per page, from 1 to 100. Default 40.
exportNotrue returns a CSV download link for the full result instead of rows. Default false.
time_zoneNoOffset from UTC in minutes, from -1440 to 1440. Default 0.

Take column names from analytics_describe rather than guessing them. A column that doesn’t exist, or that your account can’t use, returns an error rather than being ignored.

Date ranges. One query covers at most 60 days, counting both the start and end dates. For a longer period, ask for it in parts of 60 days or fewer. A longer range is refused before the report runs, with a message that says so.

Paging. Inline results come one page at a time: 40 rows unless you ask for more, up to 100. details.numFound is the total row count, so if it’s higher than the rows you got, ask for the next page.

Exports. With export: true you get export_url, a CSV link for the whole result set with the same report, columns, filters and sort. start and limit don’t apply. If the report doesn’t support export, or you ask for more dimensions than the report allows, the tool tells you before it runs anything.

Ask for rankings directly. For questions like “which were worst”, ask for the rows sorted by that column (order_by) so the sort happens before the page is cut.

analytics_status

Reports run in the background. A quick report comes back with its rows in the same call. A slower one comes back with status: "IN_PROGRESS", a request_id and poll_after_seconds. That’s a normal result, not an error. Your assistant waits that long, then calls analytics_status to collect the result.

InputRequiredDescription
request_idYesThe request_id from the query that was still running.
report_idYesThe same report_id that query used.

If the report still isn’t finished, you get the same request_id back to try again. Request IDs expire. If one is unknown or expired, run the query again.

What a query returns

FieldMeaning
statusCOMPLETED, or IN_PROGRESS when the report is still running.
report_id, titleThe report you ran.
detailsThe rows: numFound (total rows), columns and docs (this page of rows).
export_urlThe CSV link, when you asked for an export.
truncated_columnsDefault columns left out because your account isn’t entitled to them. Check this before you conclude a column is missing.
warningsNotes about a result that’s usable but incomplete.
error, codeSet only when nothing usable came back. See Errors.
trace_idA reference for this call. Quote it to support.

MRT enrichment

mrt_enrichment_query

Returns Pixalate Media Ratings Terminal (MRT) data for mobile apps, CTV apps or web domains that you already know. You choose which data widgets you want.

“What are the Pixalate risk ratings for com.example.app?”

“Show me brand safety and IVT for example.com and example.org in North America.”

InputRequiredDescription
kindYesmobile, ctv or domain.
idsYes1 to 50 IDs. A bundle ID or numeric app ID for mobile and ctv, or a bare domain such as example.com for domain. Repeated IDs are looked up once.
widgetsYesOne or more widget names from the list for that kind, below. There’s no “all widgets” option.
regionNoGLOBAL, NA, EMEA, LATAM or APAC. For domain, also US or NON-US.
deviceNomobile: GLOBAL, smartphone or tablet. ctv: roku, firetv, samsung or tvos. domain: GLOBAL, desktop or mobile.
includeSpoofingNoctv only. Set false to exclude spoofed traffic from CTV invalid-traffic figures.

Widgets by kind.

KindWidgets
mobilead-inventory, app-alerts, app-metadata, app-profile, audience-overlap, brand-safety, content-advisories, coppa-compliance, country-rankings, ctr, developer-profile, ivt, market-availability, mfa, permissions-risk, risk-ratings, store-rankings, supply-chain, traffic-quality, viewability
ctvad-inventory, app-alerts, app-metadata, app-profile, app-spoofing, audience-overlap, brand-safety, channels, coppa-compliance, country-rankings, developer-profile, ivt, market-availability, mfa, risk-ratings, store-rankings, supply-chain
domainad-inventory, brand-safety, ctr, device-distribution, domain-metadata, domain-profile, ivt, mfa, risk-ratings, site-info, site-risk, social-media-risk, sub-domains, supply-chain, traffic-quality, traffic-sources, viewability

Which widgets you can get depends on your Pixalate plan.

Narrow by region and device. Without them, a widget can return rows for every region and device it has data for. Setting region and device returns less data and a shorter answer.

What comes back. Each widget is reported on its own, so one widget failing doesn’t fail the others:

  • One ID: id, widgets and summary at the top level.
  • Two or more IDs: results, with one entry per ID (id, status, widgets, summary). An ID that isn’t found is marked error without affecting the other IDs.

Each entry in widgets has a widget, a status and records:

statusMeaning
okData in records.
no_dataPixalate has no data for this widget and ID.
errorNot returned. reason says why: not_entitled (not in your plan; ask your account manager), not_found (the widget isn’t available for this kind of ID; check the name), or unavailable (try again shortly).

summary counts the widgets requested, ok, no_data and error. Every response has a trace_id.

Errors

When a call fails, the response has an error message and a code. The message says what happened and what to do. The code tells you what kind of problem it is:

codeWhat it meansWhat to do
invalid_argumentSomething in the request isn’t valid, such as a date, a column or a paging value.Fix the input the message names.
not_foundThe report or request ID isn’t known for your account, or has expired.Run analytics_describe to see your reports, or run the query again.
permission_deniedYour account isn’t permitted to run this, or the data isn’t in your plan.Contact your Pixalate account manager.
rate_limitedA Pixalate service is busy, too many of your reports are running at once, or your analytics report quota is used up.Wait a few seconds and retry. If the message says your quota is exhausted, waiting won’t help; contact your account manager.
upstream_unavailableA Pixalate service couldn’t complete the request.Try again shortly. If it persists, email support with the trace_id.
internalSomething unexpected went wrong.Try again. If it persists, email support with the trace_id.

Every response, successful or not, carries a trace_id. Include it when you email support@pixalate.com so support can find the exact call.