Skip to main content
Legacy

This hourly T-Values Reporting API remains available for publishers who already have credentials. Talroo is aligning new reporting stacks with programmatic access described in Programmatic TAP access.

For tagging definitions, URL patterns, TAP earnings exports (t1, t2, t3), and length rules, see T-Values (Tracking Tags) instead of starting here unless you genuinely need this HTTP API.

T-Values Reporting API

Use this guide only when Talroo has provisioned username / password access for the legacy JSON reporting pipeline. Typical reporting for most publishers is the Earnings Report CSV (with optional t1–t3) plus Tracking Tags.

Credentials

Reach publishers@talroo.com if you need new access or rotations; do not propagate historical keys without confirmation Talroo still exposes this surface for your publisher id.

Authentication​

POST https://nv3xq21kwj.execute-api.us-east-1.amazonaws.com/prod/auth

Request body:

{
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD"
}

Response:

{
  "id_token": "eyJhbGciOiJIUzI1NiIs...",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600
}

Report data endpoint​

GET https://0tphaqutzi.execute-api.us-east-1.amazonaws.com/prod/reports/publisher/t_values_date_breakdown

Required headers:

Authorization: Bearer {ID_TOKEN}

Example response:

{
  "data_type": "tabular",
  "data_timestamp": 1759999999,
  "columns": ["Date", "T1", "T2", "T3", "Clicks", "Earnings"],
  "data": [
    ["2022-08-17", "value1", "value2", "value3", 150, 75.50],
    ["2022-08-16", "value1", "value2", "value3", 200, 100.00]
  ]
}

Query parameters​

ParameterTypeRequiredDescription
time_rangestringYesTime bucket for retrieval
f_t1integerNo*Include t1 groupings (1 = yes, 0 = no)
f_t2integerNo*Include t2 groupings
f_t3integerNo*Include t3 groupings
f_publisher_idstringNoFilter by Talroo feed identifier
Filters

At least one of f_t1, f_t2, or f_t3 must be 1 or the backend returns empty semantics—double-check parity with dashboards after changing filters.

Time ranges​

ValueMeaning
thisfull_dayToday through the freshest hourly shard
previous_dayFully closed prior UTC day snapshot
epoch_start~epoch_endCustom window (epoch_start and epoch_end are UNIX seconds @ daily grain)

Example

time_range=1643882400~1643885999

That window references the UTC instants backing the summarized rows (consult Talroo if you mirror finance calendars—finance still treats TAP totals as authoritative).

Time zones

Epochs are emitted in UTC, while human-readable dashboards often render using US Eastern shorthand. Normalize in your warehouse before stitching to payouts.

Response shape cheatsheet​

Columns appear based on toggles (f_t1, f_t2, f_t3). Clicks and Earnings always accompany whichever tag columns you enabled:

{
  "columns": [
    "Date",
    "T1",
    "T2",
    "T3",
    "Clicks",
    "Earnings"
  ],
  "data": [
    ["2022-08-17", "value1", "value2", "value3", 150, 75.50]
  ]
}

Error handling​

StatusMeaningTypical mitigation
200SuccessParse data; validate column order before inserts
401UnauthorizedRegenerate bearer token via /auth
404Not foundRare race—retry with exponential backoff (under 3 attempts)
429ThrottledBack off exponentially; widen intervals between pulls
500Platform issuePause automation and alert publishers@talroo.com

Operational best practices for the API tier​

  • Cadence: Most teams ingest shortly after minute 45 each hour—the dataset refresh targets that boundary.
  • Scope filters: Fetch only tag dimensions (f_tx) you materially report on; wide matrices increase payload size unnecessarily.
  • Token hygiene: Refresh ID tokens ≥5 minutes before clock skew expiry; recycle credentials if leaked.