Text reports

The same figures as the text reports in the app. Like the overview, most of them count the account and the sub-accounts under it (Top campaigns and Best hours to send count only the account the key belongs to), and they need reports access. A key user who only sees assigned contacts gets figures over those contacts, except for the two reports that cover the whole account, which answer 403 report_scope_forbidden. Delivery receipts and reply tags can still change a recent period, so read it again if you need it final.

#Texts by hour

Texts sent and delivered in each clock hour of one short window, up to 48 hours. Use it for today or yesterday, where a daily row would be a single point.

Parameters

fromstring · query: Start of the window, an ISO timestamp. Required.
tostring · query: End of the window, exclusive. Default: now. At most 48 hours after from.

Returns

data[]object[]: One row per hour that had texts, oldest first.
data[].hourstring: The hour, as a UTC timestamp such as 2026-10-31T14:00:00Z.
data[].countinteger: Texts sent in that hour.
data[].deliveredinteger: Of those, delivered so far.

Errors

HTTP	Code	When
400	`invalid_request`	`from` is missing, is not a valid time, or the window is longer than 48 hours.
400	`invalid_field`	A parameter sent twice, or too long; `field` names it.
403	`permission_denied`	The key’s user has no reports access.
503	`report_unavailable`	The report couldn’t be read. Nothing changed; retry. Do not record zeros.

curl "https://api.tryready.com/v1/reports/hourly?from=2026-10-31T00:00:00Z&to=2026-10-31T06:00:00Z" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/reports/hourly?from=2026-10-31T00:00:00Z&to=2026-10-31T06:00:00Z', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/reports/hourly?from=2026-10-31T00:00:00Z&to=2026-10-31T06:00:00Z",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [
    { "hour": "2026-10-31T01:00:00Z", "count": 120, "delivered": 114 },
    { "hour": "2026-10-31T02:00:00Z", "count": 80, "delivered": 77 }
  ]
}

#Daily text volume

Texts sent and delivered per day, oldest first, in the key user’s time zone. This counts every text created that day, MMS and texts that failed included, across the account and its sub-accounts, the same as the Reports page. The daily report counts sms_sent differently: only texts handed to the carrier, without MMS, for one account in the account time zone, so the two can differ. Use the daily report for costs, replies and opt-outs.

Parameters

daysinteger · queryDefault 15: The last N days.
from, tostring · query: A custom window instead of days: dates as YYYY-MM-DD, in the key user’s time zone, or full timestamps.

Returns

data[]object[]: One row per day.
data[].datestring: The day, YYYY-MM-DD.
data[].countinteger: Texts sent that day.
data[].deliveredinteger: Of those, delivered so far.

Errors

HTTP	Code	When
400	`invalid_field`	A parameter sent twice, or too long; `field` names it.
403	`permission_denied`	The key’s user has no reports access.
503	`report_unavailable`	The report couldn’t be read. Nothing changed; retry. Do not record zeros.

curl "https://api.tryready.com/v1/reports/volume?days=2" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/reports/volume?days=2', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/reports/volume?days=2",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [
    { "date": "2026-10-30", "count": 940, "delivered": 902 },
    { "date": "2026-10-31", "count": 310, "delivered": 281 }
  ]
}

#Top campaigns

The campaigns and drip campaigns that sent the most in the window, largest first. A campaign with no sends in the window is left out. Counts only the account the key belongs to, not its sub-accounts.

Parameters

daysinteger · queryDefault 30: The last N days.
from, tostring · query: A custom window instead of days: dates as YYYY-MM-DD, in the key user’s time zone, or full timestamps.

Returns

data[]object[]: Up to the 5 busiest.
data[].idinteger: The campaign or drip campaign id.
data[].namestring: Its name.
data[].kindstring: blast for a one time campaign, sequence for a drip campaign.
data[].created_atstring: When it was created.
data[].total_sentinteger: Texts sent in the window.
data[].deliveredinteger: Of those, delivered.
data[].failedinteger: Of those, failed.
data[].repliesinteger: Contacts who replied.
data[].delivery_ratenumber or null: Delivered over delivered plus failed, as a percent. null when nothing has resolved yet.

Errors

HTTP	Code	When
400	`invalid_field`	A parameter sent twice, or too long; `field` names it.
403	`permission_denied`	The key’s user has no reports access.
503	`report_unavailable`	The report couldn’t be read. Nothing changed; retry. Do not record zeros.

curl "https://api.tryready.com/v1/reports/top-campaigns?days=30" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/reports/top-campaigns?days=30', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/reports/top-campaigns?days=30",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [
    { "id": 77, "name": "October reactivation", "kind": "blast", "created_at": "2026-10-12T15:02:11Z", "total_sent": 4200, "delivered": 4011, "failed": 96, "replies": 233, "delivery_rate": 97.7 }
  ]
}

#Delivery breakdown

Did the texts arrive: totals, a trend per day, the reasons the failures gave, and the result for each sending number.

Parameters

daysinteger · queryDefault 30: The last N days.
from, tostring · query: A custom window instead of days: dates as YYYY-MM-DD, in the key user’s time zone, or full timestamps.
partstring · queryDefault all: Read less to answer faster: summary (totals and daily), numbers, reasons, detail (numbers and reasons) or all. A part you did not ask for comes back null, except daily, which comes back as an empty list.

Returns

data.daysinteger: The window length used.
data.totalsobject: sent, delivered, failed, pending, delivery_rate and failure_rate (percents).
data.daily[]object[]: One row per day with the same counts.
data.by_reason[]object[]: The most common failure reasons, each with reason and count.
data.reason_totalinteger: Failures that have a reason.
data.by_number[]object[]: Per sending number: phone_number, sent, delivered, failed, delivery_rate.
data.blockedobject: Texts Ready held back before sending, as compliance and undeliverable, each with attempts and recipients. Only there when you ask for summary or all; null when it can’t be read or the key user sees only assigned contacts.

Errors

HTTP	Code	When
400	`invalid_field`	A parameter sent twice, or too long; `field` names it.
403	`permission_denied`	The key’s user has no reports access.
503	`FAILURE_REASONS_UNAVAILABLE`	The failure reasons could not be read. The answer carries `retryable: true`.
503	`report_unavailable`	The report couldn’t be read. Nothing changed; retry. Do not record zeros.

curl "https://api.tryready.com/v1/reports/delivery-breakdown?days=7&part=summary" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/reports/delivery-breakdown?days=7&part=summary', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/reports/delivery-breakdown?days=7&part=summary",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "days": 7,
    "totals": { "sent": 5200, "delivered": 4980, "failed": 131, "pending": 89, "delivery_rate": 95.8, "failure_rate": 2.5 },
    "by_reason": null,
    "reason_total": null,
    "by_number": null,
    "daily": [ { "date": "2026-10-31", "sent": 310, "delivered": 281, "failed": 9 } ]
  }
}

#Reply heatmap

How many replies arrived in each hour of each weekday. It counts replies, not a reply rate, because a reply can come long after the text that earned it.

Parameters

daysinteger · queryDefault 30: The last N days.
from, tostring · query: A custom window instead of days: dates as YYYY-MM-DD, in the key user’s time zone, or full timestamps.
tzstring · queryDefault: the key user’s time zone: An IANA name such as America/New_York. An unknown name is ignored.

Returns

data[]object[]: One row for each weekday and hour that had replies.
data[].dowinteger: Day of the week, 0 for Sunday to 6 for Saturday.
data[].hourinteger: Hour of the day, 0 to 23.
data[].ninteger: Replies in that slot.
timezonestring: The time zone the slots are counted in.

Errors

HTTP	Code	When
400	`invalid_field`	A parameter sent twice, or too long; `field` names it.
403	`permission_denied`	The key’s user has no reports access.
503	`report_unavailable`	The report couldn’t be read. Nothing changed; retry. Do not record zeros.

curl "https://api.tryready.com/v1/reports/reply-heatmap?days=60&tz=America/New_York" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/reports/reply-heatmap?days=60&tz=America/New_York', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/reports/reply-heatmap?days=60&tz=America/New_York",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [ { "dow": 2, "hour": 10, "n": 41 }, { "dow": 2, "hour": 11, "n": 37 } ],
  "timezone": "America/New_York"
}

#Best hours to send

Texts sent and replies for each hour of the day, to show when people answer. The window is the last N times 24 hours, not whole days. Counts only the account the key belongs to, not its sub-accounts.

Parameters

daysinteger · queryDefault 30Max 365: The last N days.
tzstring · queryDefault: the key user’s time zone: An IANA name such as America/New_York. An unknown name is ignored.

Returns

data[]object[]: Always 24 rows, hour 0 to 23.
data[].hourinteger: Hour of the day.
data[].sentinteger: Texts sent in that hour.
data[].repliesinteger: Replies received in that hour.
data[].cohort_sentinteger: Texts sent to a known contact, the base for the next field.
data[].sent_with_replyinteger: Of those, texts whose contact replied within 7 days.
bestobject or null: The best sending window the report found. null when there is not enough data.
timezonestring: The time zone the hours are counted in.

Errors

HTTP	Code	When
400	`invalid_field`	A parameter sent twice, or too long; `field` names it.
403	`permission_denied`	The key’s user has no reports access.
403	`report_scope_forbidden`	The key’s user only sees contacts assigned to them. This report covers the whole account.
503	`report_unavailable`	The report couldn’t be read. Nothing changed; retry. Do not record zeros.

curl "https://api.tryready.com/v1/reports/hourly-pattern?days=30" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/reports/hourly-pattern?days=30', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/reports/hourly-pattern?days=30",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [ { "hour": 9, "sent": 820, "replies": 64, "cohort_sent": 801, "sent_with_reply": 70 } ],
  "best": null,
  "timezone": "America/Los_Angeles"
}

#Deliverability

Why texts fail. The last 24 hours, 7 days and 30 days, failures by group, the most common errors with advice, the result per sending number and per carrier, and the latest failures. The figures are refreshed about every 5 minutes.

Parameters

numbers_onlystring · queryDefault false: Send true to get only per_phone, faster.

Returns

summaryobject: Keyed 24h, 7d and 30d, each with total, delivered, failed, pending, delivery_rate and failure_rate.
failures_by_group[]object[]: status_group and count. status_group is the carrier’s group for the failure: UNDELIVERABLE (the phone could not take it), EXPIRED (the carrier gave up before it was delivered), REJECTED (the carrier refused it) or UNKNOWN (no receipt said why).
top_errors[]object[]: error_name, error_code, status_group, count, guidance and explanation.
per_phone[]object[]: from_number, total, delivered, failed, delivery_rate.
by_carrier[]object[]: carrier, total, delivered, failed, pending, delivery_rate, failure_rate. Carriers with fewer than 10 texts are left out.
recent_failures[]object[]: The latest failed texts, each with the reason in plain words.

Errors

HTTP	Code	When
400	`invalid_field`	A parameter sent twice, or too long; `field` names it.
403	`permission_denied`	The key’s user has no reports access.
403	`report_scope_forbidden`	The key’s user only sees contacts assigned to them. This report covers the whole account.
403	`report_scope_forbidden`	The key’s user is a team member limited to some of the account’s numbers. This report covers every number on the account.
503	`report_unavailable`	The report couldn’t be read. Nothing changed; retry. Do not record zeros.

curl "https://api.tryready.com/v1/reports/deliverability" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/reports/deliverability', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/reports/deliverability",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "summary": { "24h": { "total": 310, "delivered": 281, "failed": 9, "pending": 20, "delivery_rate": 96.9, "failure_rate": 3.1 } },
  "failures_by_group": [ { "status_group": "UNDELIVERABLE", "count": 7 } ],
  "top_errors": [],
  "per_phone": [ { "from_number": "+13105550123", "total": 310, "delivered": 281, "failed": 9, "delivery_rate": 96.9 } ],
  "by_carrier": [],
  "recent_failures": []
}