# Analytics API

> Outcome data for optimizing agents — email, LinkedIn, call, and task overviews, activity feeds, team performance, channel efficiency, and the meetings list.

- **Category:** Analytics
- **Base URL:** `https://api.reply.io/v3`
- **Official reference:** https://docs.reply.io/api-reference/reports/get-email-reporting-overview
- **In Reply's reference:** called “Reports”
- **OpenAPI:** https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/analytics.openapi.yaml
- **HTML version:** https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/analytics

## What it does

The Analytics API is eleven read-only report queries under `/v3/reporting/*`, in two shapes. Six overview reports return aggregated counts and rates: email, calls, LinkedIn, tasks, team performance, and cross-channel efficiency. Five list reports return paginated individual records: email, call, LinkedIn, and task activity, plus the meetings list. Every endpoint takes the same POST body of `filters` — a date range (or preset; the default is `lastWeek`) plus segment filters like sequences, teams, users, industries, job titles, company sizes, and countries. Overview reports also accept a `compareTo` period and return trend deltas. Note the verb: these are POST queries with filters in the body, not GETs.

## The problem it solves

This is the feedback loop. An autonomous SDR that can't measure can't optimize — it will keep sending the same message to the same segments regardless of what converts. The Analytics API closes the loop: analyze performance (which channels, segments, and senders produce `interested` replies and `meetingsBooked`), prioritize the winning segments, then adjust sequences through the Sequence API. The meetings list is the closest thing to a meetings-booked ledger the platform exposes — one honest caveat: meeting booking itself happens through Reply's scheduling product, not this API. These endpoints report the outcomes; they don't create them.

## How an agent starts using it

Start with `POST /v3/reporting/emails/overview` and an empty `filters` object — it defaults to last week's account-wide numbers. Requires an API key with the `reporting:read` scope. From there: slice by segment (re-run the overview with `industries` or `titles` filters and compare `interestedPercentage`), check `POST /v3/reporting/channel-efficiency/overview` to weigh email against LinkedIn and calls, and read `POST /v3/reporting/team-performance/meetings` for booked-meeting outcomes. When a report points at a specific campaign, drop down to `GET /v3/sequences/{id}/stats` on the Sequence API for per-step detail, and act on what you find there.

## Typical agent tasks

- Pull the email overview for last month and compare reply rates against the previous period
- Run filtered overview queries per industry or job title to find the segments that actually reply
- Compare channel efficiency to decide whether the next sequence leads with email or LinkedIn
- List meetings booked this week with the channel and sequence that produced each one
- Read team performance to see which user's outreach converts to meetings fastest

## Inputs

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `filters` | ReportingFilters | yes | Shared filter object on every report — date range (from/to or a dateRangePreset like lastWeek/lastMonth/allTime) plus segment filters such as sequenceIds, teamIds, userIds, industries, titles, companySizes, countries, and channel-specific extras (e.g. bounceTypes, sentiments for email). |
| `compareTo` | object | no | Optional comparison period (from/to) on overview reports — returns trend deltas against the previous window. |
| `top / skip` | integer | no | Query-parameter pagination on the activity-list and meetings endpoints. |

## Outputs

| Name | Type | Description |
|------|------|-------------|
| `overview` | OverviewMetrics | Aggregated counts and rates per channel — contacted, delivered, opened, replied, interested, bounced, meetingsBooked, plus percentage fields for each. |
| `items` | ActivityRecord[] | Individual email/call/LinkedIn/task activity records on the list endpoints, with hasMore for pagination. |
| `meetings` | MeetingListItem[] | Booked-meeting records — userId, source channel, contactFullName, sequenceName, bookedAt. |

## Authentication

API key as Bearer token. Send `Authorization: Bearer <API_KEY>` on every request. Required scopes: `reporting:read`. Get an API key in the Reply.io app under **Settings → API Key** (https://docs.reply.io/api-reference/authentication).

## Rate limits

100 requests/minute and 3,000 requests/hour per user (shared across all of the user's API clients). The /v3/reporting/* endpoints may throttle earlier than the general quota (see https://docs.reply.io/api-reference/rate-limits). On 429, honor the Retry-After header.

## Example

### Request — `POST /v3/reporting/emails/overview`

```bash
curl -X POST https://api.reply.io/v3/reporting/emails/overview \
  -H "Authorization: Bearer $REPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filters": { "dateRangePreset": "lastMonth", "sequenceIds": [48213] } }'
```

### Response — `200`

```json
{
  "contacted": 1240,
  "delivered": 1198,
  "opened": 611,
  "replied": 96,
  "interested": 31,
  "bounced": 42,
  "meetingsBooked": 12,
  "deliveredPercentage": 96.6,
  "repliedPercentage": 8.0,
  "interestedPercentage": 2.6
}
```

### Error — `429`

```json
{
  "type": "https://docs.reply.io/api-reference/rate-limits",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Reporting rate limit exceeded. Retry after the interval in the Retry-After header."
}
```

## Related APIs

- [Sequence API](https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/sequences.md) — Create, populate, and control multichannel outreach sequences — email, LinkedIn, and calls in one campaign object.
- [Conversations & Inbox API](https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/conversations-inbox.md) — The unified inbox as an API — read threads across email and LinkedIn, classify replies with categories, detect meeting intent, and respond.
- [AI SDR API (Jason)](https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/ai-sdr.md) — Program Jason, Reply's autonomous AI SDR — feed it knowledge bases, offers, and playbooks today; run full autopilot sequences with approval gates soon.
- [Tasks API](https://docs.reply.io/api-reference/tasks/create-a-task) — Create, assign, and complete manual touch tasks — calls, LinkedIn actions, and custom to-dos — for the humans and agents on your team.

## FAQ

**Do the reporting endpoints have their own rate limits?**

The platform limit is 100 requests/minute and 3,000/hour per user, but /v3/reporting/* endpoints may throttle earlier than the general quota. Cache overview results, batch your segment queries, and honor the Retry-After header on 429.

**Is the meetings list a way to book meetings?**

No. Meeting booking happens through Reply's scheduling product (booking calendars); there is no book-a-meeting endpoint in this API. POST /v3/reporting/team-performance/meetings is the outcomes ledger — who booked, from which channel and sequence, and when.

**Should an agent use these reports or the Sequence API stats?**

Both, for different jobs. GET /v3/sequences/{id}/stats on the Sequence API gives per-sequence and per-step numbers for tuning one campaign. The reporting endpoints aggregate across the whole account with segment filters (industry, title, company size, team) and period comparison — use them to decide where to point the next campaign.