Reports

Each report operation answers the numbers of one tab of Reports in Ricky. The API reads the same data with the same definitions, so for the same period and filters it shows what the page shows. The key needs the reports:read scope.

The periodCopy link

• from and to are days, YYYY-MM-DD, both inclusive. Send both or neither. Without them the report covers the last 7 days, today included.
• Days are America/Panama time, like the Reports pages. A message sent at 23:30 in Panama counts on that day.
• A to after today counts as today. from cannot be after today, nor after to, and a period has at most 366 days. Otherwise the answer is 400 invalid_input.
• period in the answer repeats the days the report covers and names the previous period: the same number of days, right before. Every previous number is that period.
• series has one entry per day. For a one-day period it has 24, one per hour, and period.granularity is hour.

Durations are in seconds. Times such as generated_at are ISO 8601 in UTC.

Read a reportCopy link

curl "https://getricky.ai/api/v1/reports/responses?from=2026-10-01&to=2026-10-14&channel=whatsapp" \
  -H "Authorization: Bearer $RICKY_API_KEY"

{
  "data": {
    "period": {
      "from": "2026-10-01",
      "to": "2026-10-14",
      "days": 14,
      "granularity": "day",
      "time_zone": "America/Panama",
      "previous_from": "2026-09-17",
      "previous_to": "2026-09-30"
    },
    "channel": "whatsapp",
    "responder": "all",
    "awaiting_reply_now": 3,
    "response_time": {
      "responses": 412,
      "average_seconds": 184.2,
      "median_seconds": 41,
      "p90_seconds": 520,
      "previous_average_seconds": 201.7,
      "buckets": [{ "bucket": "under_30s", "count": 170, "share": 0.41 }],
      "series": [
        {
          "slot": "2026-10-01",
          "average_seconds": 150.3,
          "median_seconds": 38,
          "previous_average_seconds": 210.1,
          "previous_median_seconds": 45
        }
      ]
    },
    "generated_at": "2026-10-14T15:30:00.000Z"
  }
}

The example is shortened. The reference lists every field and defines what each one counts.

DefinitionsCopy link

• Customer (conversations report): a conversation with at least one customer message in the period. It is new when its first message ever falls in the period.
• Response (responses report): the first message sent to the customer, other than a reaction, right after a customer message. Its time is the wait since that message. Follow-ups, automations and templates are not responses. responder=humans covers people in Ricky and in the channel's own app; responder=agents, the AI agents; a member or AI agent ID, only them.
• Resolution (resolutions report): each close in the period, from the opening of that span to the close.
• Ads: a conversation comes from an ad when a customer message carries a Meta ad referral. Spend comes from Meta for the ad account's own days, so a period's edges can differ by the time zones' offset.

Reports are computed when you call them. The Reports pages keep each result for a few minutes, so a page opened earlier can show slightly older numbers.