> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.pixalate.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pixalate.com/_mcp/server. # Tool reference > Reference for the Pixalate MCP tools analytics_describe, analytics_query, analytics_status and mrt_enrichment_query, with their inputs, outputs and error codes. 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](/mcp/access). | Tool | What it does | | ---------------------- | ------------------------------------------------------------------------------- | | `analytics_describe` | Lists the analytics reports your account can run, or the columns of one report. | | `analytics_query` | Runs an analytics report for a date range, inline or as a CSV export. | | `analytics_status` | Collects the result of a report that was still running. | | `mrt_enrichment_query` | Returns Pixalate data widgets for mobile apps, CTV apps or web domains. | > **Note** > > 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. | Input | Required | Description | | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `report_id` | No | Leave 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. | Input | Required | Description | | ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `report_id` | Yes | A report ID from `analytics_describe`, or `custom` for your own column selection. | | `date_from` | Yes | Start date, `YYYY-MM-DD`, inclusive. | | `date_to` | Yes | End date, `YYYY-MM-DD`, inclusive. The range can be at most 60 days. | | `dimensions` | For `custom` | Dimension columns. Optional for a named report, where it overrides the report's defaults. | | `metrics` | For `custom` | Metric columns. Optional for a named report, where it overrides the report's defaults. | | `filters` | No | A 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_by` | No | Dimension columns to group by. | | `order_by` | No | Column to sort by. Defaults to the report's own sort. | | `order_dir` | No | `DESC` (default) or `ASC`. | | `start` | No | Row offset for paging. Default `0`. | | `limit` | No | Rows per page, from 1 to 100. Default `40`. | | `export` | No | `true` returns a CSV download link for the full result instead of rows. Default `false`. | | `time_zone` | No | Offset 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. | Input | Required | Description | | ------------ | -------- | ------------------------------------------------------- | | `request_id` | Yes | The `request_id` from the query that was still running. | | `report_id` | Yes | The 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 | Field | Meaning | | -------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `status` | `COMPLETED`, or `IN_PROGRESS` when the report is still running. | | `report_id`, `title` | The report you ran. | | `details` | The rows: `numFound` (total rows), `columns` and `docs` (this page of rows). | | `export_url` | The CSV link, when you asked for an export. | | `truncated_columns` | Default columns left out because your account isn't entitled to them. Check this before you conclude a column is missing. | | `warnings` | Notes about a result that's usable but incomplete. | | `error`, `code` | Set only when nothing usable came back. See [Errors](#errors). | | `trace_id` | A 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." | Input | Required | Description | | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kind` | Yes | `mobile`, `ctv` or `domain`. | | `ids` | Yes | 1 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. | | `widgets` | Yes | One or more widget names from the list for that `kind`, below. There's no "all widgets" option. | | `region` | No | `GLOBAL`, `NA`, `EMEA`, `LATAM` or `APAC`. For `domain`, also `US` or `NON-US`. | | `device` | No | `mobile`: `GLOBAL`, `smartphone` or `tablet`. `ctv`: `roku`, `firetv`, `samsung` or `tvos`. `domain`: `GLOBAL`, `desktop` or `mobile`. | | `includeSpoofing` | No | `ctv` only. Set `false` to exclude spoofed traffic from CTV invalid-traffic figures. | **Widgets by kind.** | Kind | Widgets | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mobile` | `ad-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` | | `ctv` | `ad-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` | | `domain` | `ad-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`: | `status` | Meaning | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ok` | Data in `records`. | | `no_data` | Pixalate has no data for this widget and ID. | | `error` | Not 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: | `code` | What it means | What to do | | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `invalid_argument` | Something in the request isn't valid, such as a date, a column or a paging value. | Fix the input the message names. | | `not_found` | The 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_denied` | Your account isn't permitted to run this, or the data isn't in your plan. | Contact your Pixalate account manager. | | `rate_limited` | A 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_unavailable` | A Pixalate service couldn't complete the request. | Try again shortly. If it persists, email support with the `trace_id`. | | `internal` | Something 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](mailto:support@pixalate.com) so support can find the exact call.