> 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.

# Migrating from legacy APIs

> Map legacy Pixalate Media Ratings API calls (ratings2.api.pixalate.com) and legacy Analytics endpoints (dashboard.api.pixalate.com) to the current Enrichment API and Analytics Reports API, including the move from username and password to an API key.

This page is for you if your integration calls either of these hosts:

* `ratings2.api.pixalate.com`: the legacy **Media Ratings API** (2018 and 2020 epochs). Its current equivalent is the [Enrichment API](/apis/enrichment-api).
* `dashboard.api.pixalate.com`: the legacy **Analytics** reporting endpoints (2016, 2018 and 2022 epochs). The current equivalent is the [Analytics Reports API](/apis/analytics-reports-api).

For the Fraud API, see [Migrate from v2 to v3](/apis/fraud-api-v2-to-v3) instead.

## What changes

|                | Legacy APIs                                                                          | Current APIs                                       |
| -------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------- |
| Host           | `ratings2.api.pixalate.com`, `dashboard.api.pixalate.com`                            | `api.pixalate.com`                                 |
| URL pattern    | `/services/<epoch>/<class>/<method>?...`                                             | Resource paths, such as `/api/v2/mrt/apps/<appId>` |
| Authentication | `username` and `password` query parameters                                           | API key in the `x-api-key` header                  |
| JSONP          | Optional `callback` parameter                                                        | Not supported. Responses are always JSON.          |
| Errors         | With `callback`, most errors came back as `200` with the real status inside the body | Standard HTTP status codes                         |

## Step 1: Get an API key

The current APIs don't accept a username and password. Ask your Pixalate account manager for an API key, then send it in the `x-api-key` header on every request. See [Authentication and API keys](/apis/authentication).

Remove `username`, `password` and `callback` from every URL you call. If your code parsed a JSONP wrapper or checked a `status` code inside a `200` response, switch it to read the HTTP status code instead. See [Quotas, limits and errors](/apis/quotas-and-errors).

## Media Ratings API to Enrichment API

### Media Ratings calls

| Legacy call (2018 or 2020 epoch)              | Enrichment API call                                                                              | Reference                                                                       |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `GET .../Ratings/getApp?appId=<id>`           | `GET /api/v2/mrt/apps/<appId>`                                                                   | [Get mobile app data](/api-reference/enrichment-apps/get-mobile-app-data)       |
| `GET .../Ratings/getCtvApp?appId=<id>`        | `GET /api/v2/mrt/ctv/<appId>`                                                                    | [Get CTV app data](/api-reference/enrichment-ctv/get-ctv-app-data)              |
| `GET .../Ratings/getDomain?adDomain=<domain>` | `GET /api/v2/mrt/domains/<adDomain>`                                                             | [Get domain data](/api-reference/enrichment-domains/get-domain-data)            |
| `POST .../Ratings/importApps`                 | `POST /api/v2/mrt/apps`                                                                          | [Batch mobile apps](/api-reference/enrichment-apps/batch-get-mobile-apps-data)  |
| `POST .../Ratings/importCtvApps`              | `POST /api/v2/mrt/ctv`                                                                           | [Batch CTV apps](/api-reference/enrichment-ctv/batch-get-ctv-apps-data)         |
| `POST .../Ratings/importDomains`              | `POST /api/v2/mrt/domains`                                                                       | [Batch domains](/api-reference/enrichment-domains/batch-get-domains-data)       |
| `GET .../Ratings/accountBalance`              | `GET /api/v2/mrt/apps`, `GET /api/v2/mrt/ctv` and `GET /api/v2/mrt/domains` (the `quota` object) | [Mobile apps metadata](/api-reference/enrichment-apps/get-mobile-apps-metadata) |
| `GET .../Ratings/getLastDataUpdatedInfo`      | The same metadata calls (the `database.lastUpdated` field)                                       | [Domains metadata](/api-reference/enrichment-domains/get-domains-metadata)      |

All Enrichment API paths are on `https://api.pixalate.com`.

### Media Ratings example

#### Legacy

```bash
curl "https://ratings2.api.pixalate.com/services/2020/Ratings/getDomain?adDomain=example.com&region=GLOBAL&device=GLOBAL&username=YOUR_USERNAME&password=YOUR_PASSWORD"
```

#### Enrichment API

```bash
curl "https://api.pixalate.com/api/v2/mrt/domains/example.com?region=GLOBAL&device=GLOBAL" \
  -H "x-api-key: $PIXALATE_API_KEY"
```

### Parameters on single lookups

| Legacy parameter       | Enrichment API          | Notes                                                                                                              |
| ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `appId`                | `appId` path segment    | Mobile apps: the Google Play package name or the App Store track ID.                                               |
| `adDomain`             | `adDomain` path segment |                                                                                                                    |
| `region`               | `region`                | Same values: `GLOBAL`, `NA`, `EMEA`, `LATAM`, `APAC`.                                                              |
| `device`               | `device`                | Mobile apps: `GLOBAL`, `smartphone`, `tablet`. CTV apps: `roku`, `firetv`. Domains: `GLOBAL`, `desktop`, `mobile`. |
| `widget`               | `widget`                | Still a comma-separated list. See [Widgets](#widgets).                                                             |
| `includeSpoofing`      | `includeSpoofing`       | CTV apps only.                                                                                                     |
| `username`, `password` | `x-api-key` header      |                                                                                                                    |
| `callback`             | None                    | Responses are always JSON.                                                                                         |
| `pretty`               | `pretty`                |                                                                                                                    |

The legacy mobile app lookup also took `iabv1`, `appStore` and `ignoreCase`. The Enrichment API reference doesn't document these parameters. If you rely on one, contact [support@pixalate.com](mailto:support@pixalate.com) before you migrate.

### Batch lookups

The batch flow works the same way. You `POST` a `text/plain` body with one identifier per line and get back the URL of a newline-delimited JSON report. The report URL returns `404` until processing finishes, so poll it.

| Legacy                                  | Enrichment API                                                                                                             |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `importApps?region=&device=&widget=`    | `POST /api/v2/mrt/apps?region=&device=`. The reference documents `region` and `device` on this endpoint, but not `widget`. |
| `importCtvApps?region=&widget=`         | `POST /api/v2/mrt/ctv`. The reference documents only `pretty` on this endpoint.                                            |
| `importDomains?region=&device=&widget=` | `POST /api/v2/mrt/domains`. The reference documents only `pretty` on this endpoint.                                        |

For report format and polling details, see the [Enrichment API](/apis/enrichment-api) guide.

### Responses

The 2020-epoch lookups and the Enrichment API return the same top-level shape: `status`, `numFound`, and a `docs` array with one entry per region and device combination, grouped into widgets. Check the field names you use against the field reference for [mobile apps](/apis/enrichment-api-mobile-fields), [CTV apps](/apis/enrichment-api-ctv-fields) or [domains](/apis/enrichment-api-domain-fields).

The 2018-epoch lookups returned a flat record without widgets, so if you're on 2018, map each field you use to its widget field in the field reference.

### Widgets

These widget names are the same in the Media Ratings 2020 epoch and the Enrichment API:

| Supply type | Widgets with the same name                                                                                                                                                                                                                                            |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mobile apps | `appOverview`, `appDetails`, `pixalateAdvisories`, `riskOverview`, `developerOverview`, `trafficOverview`, `brandSafety`, `appPermissions`, `trafficOverlap`, `authorizedSellers`, `invalidTraffic`, `viewability`, `inventory`, `coppa`                              |
| CTV apps    | `appOverview`, `riskOverview`, `pixalateAdvisories`, `appSpoofing`, `appDetails`, `developerOverview`, `channels`, `brandSafety`, `trafficOverlap`, `authorizedSellers`, `invalidTraffic`, `inventory`                                                                |
| Domains     | `domainOverview`, `riskOverview`, `domainDetails`, `trafficQualityRisk`, `siteRisk`, `siteInfo`, `brandSafetyRisk`, `socialMediaRisk`, `invalidTraffic`, `inventory`, `authorizedSellers`, `viewability`, `ctr`, `trafficSources`, `subDomains`, `deviceDistribution` |

The legacy mobile app widgets `adCapabilities` and `interactiveElements` aren't in the Enrichment API reference. The Enrichment API also has widgets the legacy API didn't document, such as `mfa`. See the [Enrichment API](/apis/enrichment-api) guide for the full list.

### Quota balance and last-updated date

`accountBalance` returned one entry per entity. In the Enrichment API, each supply type has its own metadata call, which returns a `quota` object and doesn't use any quota.

| `accountBalance` field            | Enrichment API metadata field                                      |
| --------------------------------- | ------------------------------------------------------------------ |
| `Entity` (`App`, `CTV`, `Domain`) | Which endpoint you call: `/mrt/apps`, `/mrt/ctv` or `/mrt/domains` |
| `Quota`                           | `quota.limit`                                                      |
| `Consumed`                        | `quota.used`                                                       |
| `Remaining`                       | `quota.available`                                                  |
| `Quota End Date`                  | `quota.expiry` (when the quota refreshes)                          |

`getLastDataUpdatedInfo` returned `app.lastUpdatedDate` and `domain.lastUpdatedDate`. Use `database.lastUpdated` from `GET /api/v2/mrt/apps` and `GET /api/v2/mrt/domains` instead.

How quota is counted is described in [Quotas, limits and errors](/apis/quotas-and-errors).

## Legacy Analytics to Analytics Reports API

### Analytics calls

| Legacy (2016, 2018 or 2022 epoch)                                           | Analytics Reports API                                                           |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `https://dashboard.api.pixalate.com/services/<epoch>/Report/getDetails?...` | `GET https://api.pixalate.com/api/v2/analytics/reports/<reportId>?...`          |
| `getExportUri` in the path                                                  | Add `exportUri=true` to the query string                                        |
| `reportId` query parameter                                                  | `reportId` path segment. If you didn't send a `reportId` before, use `default`. |
| `username`, `password`                                                      | `x-api-key` header                                                              |
| `callback`                                                                  | None. Responses are always JSON.                                                |
| `q`, `timeZone`, `start`, `limit`, `isAsync`, `isLargeResultSet`            | Same names                                                                      |

See the [Analytics Reports API reference](/api-reference/analytics-reports/get-analytics-report) for every parameter.

### Analytics example

#### Legacy

```bash
curl "https://dashboard.api.pixalate.com/services/2018/Report/getDetails?username=YOUR_USERNAME&password=YOUR_PASSWORD&timeZone=0&start=0&limit=20&q=adDomain,impressions,givtSivtRate%20WHERE%20day%3E%3D'2026-02-06'%20AND%20day%3C%3D'2026-02-06'%20ORDER%20BY%20impressions%20DESC"
```

#### Analytics Reports API

```bash
curl "https://api.pixalate.com/api/v2/analytics/reports/default?timeZone=0&start=0&limit=20&q=adDomain,impressions,givtSivtRate%20WHERE%20day%3E%3D'2026-02-06'%20AND%20day%3C%3D'2026-02-06'%20ORDER%20BY%20impressions%20DESC" \
  -H "x-api-key: $PIXALATE_API_KEY"
```

URL-encode the `q` value. For the query syntax, see [Query language](/apis/analytics-query-language).

### Renamed metrics and labels

If you're moving from an older epoch, check your queries and CSV processing for these renames.

#### 2016 to 2018: renamed dimensions and metrics

These names changed in the 2018 epoch. Use the 2018 name in your `q` queries.

| 2016 name                         | 2018 name                     |
| --------------------------------- | ----------------------------- |
| `deviceId` (dimension)            | `deviceModelId`               |
| `nonGivtSivtViews`                | `views`                       |
| `nonGivtSivtNonViews`             | `nonViews`                    |
| `nonGivtSivtUndeterminedImps`     | `undeterminedImps`            |
| `nonGivtSivtMeasuredImpressions`  | `measuredImpressions`         |
| `nonGivtSivtMeasuredRate`         | `measuredRate`                |
| `nonGivtSivtViewability`          | `viewability`                 |
| `nonGivtSivtViewsRate`            | `viewsRate`                   |
| `nonGivtSivtNonViewsRate`         | `nonViewsRate`                |
| `nonGivtSivtUndeterminedImpsRate` | `undeterminedImpsRate`        |
| `clickOrphans`                    | `totalClicks`                 |
| `conversionOrphans`               | `totalConversions`            |
| `convRate`                        | `totalConvRate`               |
| `givtClickOrphans`                | `givtTotalClicks`             |
| `givtClickOrphansRate`            | `givtTotalClicksRate`         |
| `givtConversionOrphans`           | `givtTotalConversions`        |
| `givtConvsOrphansRate`            | `givtTotalConvsRate`          |
| `nonGivtClickOrphans`             | `nonGivtTotalClicks`          |
| `nonGivtConversionOrphans`        | `nonGivtTotalConversions`     |
| `nonGivtSivtClickOrphans`         | `nonGivtSivtTotalClicks`      |
| `nonGivtSivtConversionOrphans`    | `nonGivtSivtTotalConversions` |
| `sivtClickOrphans`                | `sivtTotalClicks`             |
| `sivtClickOrphansRate`            | `sivtTotalClicksRate`         |
| `sivtConversionOrphans`           | `sivtTotalConversions`        |
| `sivtConvsOrphansRate`            | `sivtTotalConvsRate`          |

#### 2018 to 2022: renamed CSV column labels

The 2022 epoch renamed these column labels in exported CSV files. Metric names in queries didn't change. If your code reads CSV exports by header label, update it.

| Metric                                      | 2018 label                           | 2022 label                         |
| ------------------------------------------- | ------------------------------------ | ---------------------------------- |
| `impressions`                               | Gross Tracked Ads                    | Gross Ad Counts                    |
| `shareOfImpressions`                        | Share of Gross Tracked Ads %         | Share of Gross Ad Counts %         |
| `ssaiImpressions`                           | Gross SSAI Tracked Ads               | Gross SSAI Ad Counts               |
| `ssaiImpressionsRate`                       | Gross SSAI Tracked Ads %             | Gross SSAI Ad Counts %             |
| `ssaiTransparentImpressions`                | Gross SSAI Transparent Tracked Ads   | Gross SSAI Transparent Ad Counts   |
| `ssaiTransparentImpressionsRate`            | Gross SSAI Transparent Tracked Ads % | Gross SSAI Transparent Ad Counts % |
| `ipv6Impressions`                           | Gross IPv6 Tracked Ads               | Gross IPv6 Ad Counts               |
| `ipv6ImpressionsRate`                       | Gross IPv6 Tracked Ads %             | Gross IPv6 Ad Counts %             |
| `duplicateImps`                             | Gross Duplicate Tracked Ads          | Gross Duplicate Ad Counts          |
| `duplicateImpsRate`                         | Gross Duplicate Tracked Ads %        | Gross Duplicate Ad Counts %        |
| `nonGivtImpressions`                        | Tracked Ads                          | Ad Counts                          |
| `shareOfNonGivtImpressions`                 | Share of Tracked Ads %               | Share of Ad Counts %               |
| `nonGivtSsaiImpressions`                    | SSAI Tracked Ads                     | SSAI Ad Counts                     |
| `nonGivtSsaiImpressionsRate`                | SSAI Tracked Ads %                   | SSAI Ad Counts %                   |
| `nonGivtSsaiTransparentImpressions`         | SSAI Transparent Tracked Ads         | SSAI Transparent Ad Counts         |
| `nonGivtSsaiTransparentImpressionsRate`     | SSAI Transparent Tracked Ads %       | SSAI Transparent Ad Counts %       |
| `nonGivtIpv6Impressions`                    | IPv6 Tracked Ads                     | IPv6 Ad Counts                     |
| `nonGivtIpv6ImpressionsRate`                | IPv6 Tracked Ads %                   | IPv6 Ad Counts %                   |
| `nonGivtDuplicateImps`                      | Duplicate Tracked Ads                | Duplicate Ad Counts                |
| `nonGivtDuplicateImpsRate`                  | Duplicate Tracked Ads %              | Duplicate Ad Counts %              |
| `nonGivtSivtImpressions`                    | Net Tracked Ads                      | Net Ad Counts                      |
| `shareOfNonGivtSivtImpressions`             | Share of Net Tracked Ads %           | Share of Net Ad Counts %           |
| `nonGivtSivtSsaiImpressions`                | Net SSAI Tracked Ads                 | Net SSAI Ad Counts                 |
| `nonGivtSivtSsaiImpressionsRate`            | Net SSAI Tracked Ads %               | Net SSAI Ad Counts %               |
| `nonGivtSivtSsaiTransparentImpressions`     | Net SSAI Transparent Tracked Ads     | Net SSAI Transparent Ad Counts     |
| `nonGivtSivtSsaiTransparentImpressionsRate` | Net SSAI Transparent Tracked Ads %   | Net SSAI Transparent Ad Counts %   |
| `nonGivtSivtIpv6Impressions`                | Net IPv6 Tracked Ads                 | Net IPv6 Ad Counts                 |
| `nonGivtSivtIpv6ImpressionsRate`            | Net IPv6 Tracked Ads %               | Net IPv6 Ad Counts %               |
| `nonGivtSivtDuplicateImps`                  | Net Duplicate Tracked Ads            | Net Duplicate Ad Counts            |
| `nonGivtSivtDuplicateImpsRate`              | Net Duplicate Tracked Ads %          | Net Duplicate Ad Counts %          |
| `givtImpressions`                           | GIVT Tracked Ads                     | GIVT Ad Counts                     |
| `givtImpsRate`                              | GIVT Tracked Ads %                   | GIVT Ad Counts %                   |
| `shareOfGivtImpressions`                    | Share of GIVT Tracked Ads %          | Share of GIVT Ad Counts %          |
| `givtIpv6Impressions`                       | IPv6 GIVT Tracked Ads                | IPv6 GIVT Ad Counts                |
| `givtIpv6ImpressionsRate`                   | IPv6 GIVT Tracked Ads %              | IPv6 GIVT Ad Counts %              |
| `sivtImpressions`                           | SIVT Tracked Ads                     | SIVT Ad Counts                     |
| `sivtImpsRate`                              | SIVT Tracked Ads %                   | SIVT Ad Counts %                   |
| `shareOfSivtImpressions`                    | Share of SIVT Tracked Ads %          | Share of SIVT Ad Counts %          |
| `shareOfGivtSivtImpressions`                | Share of IVT Tracked Ads %           | Share of IVT Ad Counts %           |
| `sivtIpv6Impressions`                       | IPv6 SIVT Tracked Ads                | IPv6 SIVT Ad Counts                |
| `givtSivtIpv6Impressions`                   | IPv6 IVT Tracked Ads                 | IPv6 IVT Ad Counts                 |
| `sivtIpv6ImpressionsRate`                   | IPv6 SIVT Tracked Ads %              | IPv6 SIVT Ad Counts %              |
| `givtSivtIpv6ImpressionsRate`               | IPv6 IVT Tracked Ads %               | IPv6 IVT Ad Counts %               |

## Timelines

Contact your Pixalate account manager for timelines on the legacy APIs and for help planning your migration. For technical questions, contact [support@pixalate.com](mailto:support@pixalate.com).