Read accounts, ads & reports

Start with an active connection. All examples target the hosted development API. Set TGADS_TOKEN, CONNECTION_ID and ACCOUNT_ID locally from your own token and returned IDs.

Accounts and ads

# Accounts visible to the connected session (REST response: array).
curl --fail-with-body \
  "https://tgads.tlmtr.dev/v1/connections/$CONNECTION_ID/api/accounts" \
  -H "Authorization: Bearer $TGADS_TOKEN"

# First page of ads for one account.
curl --fail-with-body \
  "https://tgads.tlmtr.dev/v1/connections/$CONNECTION_ID/api/accounts/$ACCOUNT_ID/ads" \
  -H "Authorization: Bearer $TGADS_TOKEN"

Ad listing is paginated. Pass the returned nextCursor as the next request's cursor until nextCursor is null. Treat cursors as opaque values; do not calculate them or reuse them for another account.

const origin = "https://tgads.tlmtr.dev";
const token = process.env.TGADS_TOKEN!;
const connectionId = process.env.CONNECTION_ID!;
const accountId = process.env.ACCOUNT_ID!;
const base = `${origin}/v1/connections/${encodeURIComponent(connectionId)}`;
let cursor: string | undefined;
const seen = new Set<string>();

do {
  const url = new URL(
    `${base}/api/accounts/${encodeURIComponent(accountId)}/ads`,
  );
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const page = await response.json();
  console.log(page.items); // Handle each page in your application.
  cursor = page.nextCursor ?? undefined;
  if (cursor && seen.has(cursor)) throw new Error("Repeated pagination cursor");
  if (cursor) seen.add(cursor);
} while (cursor);

Inspect a creative

Use an ad's returned numeric ID as AD_ID:

curl --fail-with-body \
  "https://tgads.tlmtr.dev/v1/connections/$CONNECTION_ID/api/accounts/$ACCOUNT_ID/ads/$AD_ID" \
  -H "Authorization: Bearer $TGADS_TOKEN"

Ad details include normalized form fields and safe preview metadata, such as copy, destination and media presence. Raw upstream HTML, media access tokens and media file downloads are not part of this response.

Daily statistics

curl --fail-with-body --get \
  "https://tgads.tlmtr.dev/v1/connections/$CONNECTION_ID/api/accounts/$ACCOUNT_ID/stats" \
  -H "Authorization: Bearer $TGADS_TOKEN" \
  --data-urlencode 'period=day' \
  --data-urlencode 'month=202608'

Use a month with data in your account. Month parameters use YYYYMM, not a date range. The example month is illustrative. Nonempty five-minute statistics remain a verification gap; start with daily data.

Monthly reports and CSV

curl --fail-with-body --get \
  "https://tgads.tlmtr.dev/v1/connections/$CONNECTION_ID/api/accounts/$ACCOUNT_ID/report" \
  -H "Authorization: Bearer $TGADS_TOKEN" \
  --data-urlencode 'month=202608'

curl --fail-with-body --get \
  "https://tgads.tlmtr.dev/v1/connections/$CONNECTION_ID/api/accounts/$ACCOUNT_ID/report.csv" \
  -H "Authorization: Bearer $TGADS_TOKEN" \
  --data-urlencode 'month=202608' \
  --output account-report.csv

Monthly report amounts are exact decimal strings. Preserve them as decimals in financial calculations instead of converting them to binary floating-point numbers. Currency is supplied by the response. Empty exports can return NO_DATA.

Location candidates

curl --fail-with-body --get \
  "https://tgads.tlmtr.dev/v1/connections/$CONNECTION_ID/api/accounts/$ACCOUNT_ID/locations" \
  -H "Authorization: Bearer $TGADS_TOKEN" \
  --data-urlencode 'country=UA' \
  --data-urlencode 'query=К' \
  --data-urlencode 'offset=0'

The query is exactly one non-whitespace character. It is not a full city-name search. Follow nextOffset when returned. region is a display label, not a parent location ID; coordinates and exhaustive geographic coverage are not available.

The API reference lists every supported route, its parameters and response schemas.