> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-reporter-looker-studio.md).

# Building a Looker Studio dashboard with the Tracker API

Use the Tracker API as the data source for a custom Google Apps Script community connector. The route and scope retain the legacy `reporter` identifier for compatibility. A reporting dashboard normally needs only `reporter:read`; keep scans and project changes outside the connector unless the integration has a separate, explicit write workflow.

## Before you start

You need:

* A Rankability API key with `reporter:read`.
* Access to Google Looker Studio and Google Apps Script.
* At least one Rankability Track project with result data.
* A plan for which client, projects, platforms, and date range the dashboard should display.

Create a dedicated read-only key rather than reusing a key that can run scans or edit projects. See [Authentication and API scopes](/api/api-authentication.md) for key setup.

## Choose the route for each chart

Prefix every request with:

```
https://app.rankability.com/api/agent/v1
```

| Dashboard element                      | Tracker route (legacy `/reporter` namespace) |
| -------------------------------------- | -------------------------------------------- |
| Project selector or project table      | `GET /reporter/projects`                     |
| Current project configuration and SPI  | `GET /reporter/projects/:id`                 |
| Current platform result detail         | `GET /reporter/projects/:id/results`         |
| Time series up to 90 days              | `GET /reporter/projects/:id/trends`          |
| Organization or client scorecards      | `GET /reporter/summary`                      |
| Client AI mention and citation summary | `GET /reporter/brand-summary?client_id=...`  |

Use the [Tracker API endpoint reference](/api/api-reporter-endpoints.md) for filters and response fields. Do not combine rows from different clients unless the dashboard is intentionally an organization-level view.

## Implement the connector

1. Store the Rankability API key in the connector user's properties or another server-side secret store. Never place it in a report field, URL, sheet, or browser-visible script setting.
2. Send `Authorization: Bearer YOUR_KEY` with each request.
3. Declare a stable Looker Studio schema. Keep identifiers and labels as dimensions; expose numeric values such as SPI, rank, mentions, citations, and coverage as metrics only when their source fields are present.
4. Map the selected Tracker response into rows that match that schema.
5. Cache identical reads in Apps Script. Include the organization, client, project, route, query parameters, and snapshot method in the cache key.
6. Paginate `/reporter/projects` instead of assuming the first page contains every project.

## Preserve result meaning

The default results request uses `snapshot=latest_per_platform`. It can combine the newest successful result for each platform after a newer run finishes only partially. Retain `snapshot.method`, `latest_run_id`, result-source run IDs, run status, and platform coverage in the connector data. A missing platform is not a zero, and a partial run is not a complete measurement.

For trends, retain each point's `run_status` and coverage. For SPI, use the returned score and applicable component fields rather than recomputing a different score in Looker Studio. Read [Understanding SPI](/track/understanding-spi.md) before presenting it to clients.

## Control freshness and limits

Set dashboard freshness close to the project's tracking cadence. Reading the API does not create newer tracking data. A scan requires `reporter:run`, can consume credits, and should not be triggered by every dashboard refresh.

Current plans allow 30, 60, or 120 Agent API requests per minute per key, depending on the plan. Integrations should read `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` instead of hard-coding a value. Respect `Retry-After` on `429` responses and use bounded exponential backoff. Review [API credits, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md) before scheduling refreshes.

## Troubleshooting

* **`401 unauthorized`** — Replace an invalid or revoked key; do not log the key while diagnosing it.
* **`403 forbidden`** — Add `reporter:read` to the connector's key.
* **`404 not_found`** — Confirm that the ID belongs to the authenticated organization.
* **Blank chart after a successful request** — Check the snapshot coverage, selected client, field types, and null handling before treating it as no performance.
* **Frequent `429` responses** — Reduce refresh frequency, cache repeated requests, and consolidate route calls.

Start by validating the same request with the curl examples in [Getting started with the Tracker API](/api/api-reporter-getting-started.md), then implement the connector mapping.