Following the instructions below, you can load TrueClicks data through REST API.
Prerequisites
Before using the API, ensure you have a TrueClicks data connector key:
Log in to TrueClicks and navigate to the Reporting page
Scroll down to the Data Connector section
Enter a key of your choice, and click the Create New Key
This process generates a Username and Token, which you’ll use later, for example, when integrating with Google Sheets, Looker Studio, or through REST API.
Accessing data with the REST API
TrueClicks data is available through our REST API. Every endpoint is a standard HTTPS GET request that returns JSON, so you can pull data into a spreadsheet, a BI tool, or your own scripts.
Example:
Steps:
Open the URL in your browser
Enter your data connector username and token (as the password) in the credentials pop-up
Retrieve account-level aggregated results for all your accounts in JSON format
Available data sets in REST API
You can access the following datasets via REST API:
Data set | URL | Description |
Accounts | The connected ad accounts in your environment, with their ID, name, and platform. Use the account ID here to filter the other endpoints.
Optional parameters: | |
Account-level results (current) | The latest audit and monitoring results aggregated per account, including the TrueClicks score, issue counts, and audit findings. | |
Account-level results (historical) | The same account-level results, with weekly history going back up to 1 year. | |
Check-level results (current) | The latest score or value for every individual audit and monitoring check, per account. Includes how much fixing each check would raise the account's TrueClicks score. Optional parameters: | |
Check output table | The detailed rows behind a single check for one account (the entities the check flagged). Get the ruleKey from the check-level results endpoint above.
Required parameters: | |
Performance monitoring alerts | Currently triggered performance alerts. Each row is a metric that breached its threshold or fluctuation limit in the latest run of an active alert definition, with the current and previous values, the change, and the campaigns involved.
Optional parameters: | |
Performance alert output table | The per-campaign metric rows behind a triggered performance alert. Get perfmonId and perfmonDefinitionMetricId from the performance monitoring alerts endpoint above.
Required parameters: | |
Target and budget pacing (current) | Target and budget pacers that are currently running, with their pacing and efficiency status.
Optional parameters: | |
Target and budget pacing (all) | All target and budget pacers, including finished and future scheduled periods.
Optional parameters: | |
Users | Active users and pending invitations. | |
Users' My Accounts | One row per user for each account they've picked as a My Account. A personal preference list, not an access-permission list.
Optional parameters: | |
Tasks | All target and budget pacers, including finished and future scheduled periods.
Optional parameters: accountIdsFilter | |
Account labels | The labels applied to your accounts, for grouping and filtering.
Optional parameters: |
Filtering results by account
Add accountIdsFilter to limit results to specific accounts. Repeat the parameter for each account you want, and leave it off to return all accounts you have access to.
Example:
Steps:
Replace the
accountId=111,222in the URL with your actual account IDs (visible in the TrueClicks interface URL)Open the updated URL in your browser
If prompted, enter your data connector username and token as the credentials
Retrieve the output table in JSON format for the specified account and check
Check-level output table results
Some checks have table outputs with extra detail rows. Use the check output table endpoint (audit-rule-output-table) to retrieve those.
Example:
Steps:
Replace the
accountId=123in the URL with your actual account ID (visible in the TrueClicks interface URL)Open the updated URL in your browser
If prompted, enter your data connector username and token as the credentials
Retrieve the output table in JSON format for the specified account and check
Key Parameters:
accountId - your account’s unique ID, found in the TrueClicks interface URL
ruleKey: The internal key for TrueClicks checksruleKey parameter - there are 2 ways you can retrieve the internal key for TrueClicks checks:
Retrieve this from the REST API endpoint for check-level data (field: ruleKey).
Alternatively, convert the check name in the TrueClicks UI to camel-case format.
Example:urgent-broken-asset-url→Urgent_BrokenAssetUrl.
OpenAPI specification (for developers)
If you're building an integration, the full API is described in a machine-readable OpenAPI specification. It lists every endpoint, its parameters, and its response schemas, so you can import it into your API client or code generator instead of wiring requests up by hand.
Specification URL:
Import it into a tool like Postman or an OpenAPI code generator to scaffold requests automatically. Authenticate with your data connector username and token over HTTP Basic auth, the same credentials used for the endpoints above.