> ## Documentation Index > Fetch the complete documentation index at: https://developer.mailbeast.ai/llms.txt > Use this file to discover all available pages before exploring further. # Campaign analytics > Aggregate engagement for one campaign. Ask for extra breakdowns with `breakdown=smtp,sequence,bounce` – each is an extra query, so request only what you will read. Requires one of the following scopes: `metrics:read`, `all:read`, `all:all`. ## OpenAPI ````yaml /openapi.json get /v1/campaigns/{id}/analytics openapi: 3.0.0 info: title: MailBeast Public API description: >- Task-shaped REST API for campaigns, leads, deliverability, verification and lead discovery. Authenticate with an API key (`Authorization: Bearer mb_live_…`); the workspace is resolved from the key. version: '1' contact: {} servers: - url: https://api.mailbeast.ai security: [] tags: - name: API Keys description: Create, list and revoke API keys programmatically. - name: Campaigns description: Create, configure, launch and monitor email campaigns. - name: Leads description: Add, read, update and bulk-manage a campaign’s leads. - name: Workspace description: Read usage, subscription and workspace identity. - name: Email Accounts description: >- Connect and manage the sending mailboxes your campaigns send from (SMTP/IMAP or native OAuth). - name: Analytics description: Engagement reporting – per campaign, over time, and across the workspace. - name: Lead Finder description: >- Discover new companies and leads. List past searches and poll a running search’s progress. paths: /v1/campaigns/{id}/analytics: get: tags: - Analytics summary: Campaign analytics description: >- Aggregate engagement for one campaign. Ask for extra breakdowns with `breakdown=smtp,sequence,bounce` – each is an extra query, so request only what you will read. Requires one of the following scopes: `metrics:read`, `all:read`, `all:all`. operationId: analytics_getCampaignAnalytics parameters: - name: id required: true in: path description: Campaign id. schema: type: string example: c1a2b3d4-... - name: startDate required: false in: query description: >- Start of the reporting window (ISO-8601). ⚠️ Reporting is by whole calendar day in your workspace timezone – the time component is ignored, so this date counts from the START of that day. schema: example: '2026-06-01T00:00:00Z' type: string - name: endDate required: false in: query description: >- End of the reporting window (ISO-8601). Defaults to now. ⚠️ Inclusive and by whole calendar day (time component ignored) – this counts through the END of that day in your workspace timezone. schema: example: '2026-06-30T23:59:59Z' type: string - name: excludeOOO required: false in: query description: >- Exclude out-of-office auto-replies from reply counts and reply rate. Mirrors the dashboard toggle. schema: default: false example: true type: boolean - name: breakdown required: false in: query description: >- Extra breakdowns to include. Repeat the param or pass a comma-separated list. Each one costs an extra query, so ask only for what you will read. schema: example: - sequence - bounce type: array items: type: string enum: - smtp - sequence - bounce responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignAnalyticsApiResponseDto' '400': description: The request body or parameters failed validation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: validation_failed message: One or more fields are invalid. status: 400 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f details: - name should not be empty '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authentication_error code: unauthenticated message: Missing or invalid API key. status: 401 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '403': description: >- The key lacks a required scope, or the plan does not include API access. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authorization_error code: permission_denied message: This API key is missing the required scope. status: 403 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '404': description: The resource does not exist in your workspace. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: not_found message: Resource not found. status: 404 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '429': description: >- Rate limit exceeded - retry after the interval in the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: rate_limit_error code: rate_limited message: >- Too many requests. Retry after the interval in the Retry-After header. status: 429 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f retryAfter: 30 security: - ApiKey: [] components: schemas: CampaignAnalyticsApiResponseDto: type: object properties: campaignId: type: string example: c1a2b3d4-... period: $ref: '#/components/schemas/AnalyticsPeriodView' totals: $ref: '#/components/schemas/AnalyticsTotalsView' bySmtp: description: Present only when requested via `breakdown=smtp`. type: array items: $ref: '#/components/schemas/SmtpBreakdownView' bySequence: description: Present only when requested via `breakdown=sequence`. type: array items: $ref: '#/components/schemas/SequenceBreakdownView' bounceBreakdown: description: Present only when requested via `breakdown=bounce`. allOf: - $ref: '#/components/schemas/BounceBreakdownView' required: - campaignId - period - totals ApiErrorDto: type: object properties: error: $ref: '#/components/schemas/ApiErrorBodyDto' required: - error AnalyticsPeriodView: type: object properties: start: type: string example: '2026-06-01T00:00:00.000Z' end: type: string example: '2026-06-30T23:59:59.000Z' clamped: type: boolean example: false description: >- true = your requested start was older than the plan retention window and was moved forward. The data you got is real but shorter than you asked for. retentionDays: type: number example: 90 description: Days of history your plan retains. required: - start - end - clamped - retentionDays AnalyticsTotalsView: type: object properties: sent: type: number example: 1200 description: Emails handed to the provider. failed: type: number example: 8 description: Sends that permanently failed before delivery. delivered: type: number example: 1186 description: Sent minus bounced. leadsContacted: type: number example: 640 description: Distinct leads that received at least one email. opens: $ref: '#/components/schemas/EngagementCountView' clicks: $ref: '#/components/schemas/EngagementCountView' replies: type: number example: 26 description: Distinct leads who replied. bounces: type: number example: 14 description: >- All bounces. Ask for `breakdown=bounce` to split hard/soft and by reason. unsubscribed: type: number example: 5 description: Unsubscribes in the window. positiveLeads: type: number example: 21 description: >- Leads currently in a positive state (interested / meeting / converted). conversions: type: number example: 6 description: Conversions attributed in the window. conversionValue: type: number example: 18000 nullable: true description: Total value of those conversions, in your workspace currency. rates: $ref: '#/components/schemas/AnalyticsRatesView' required: - sent - failed - delivered - leadsContacted - opens - clicks - replies - bounces - unsubscribed - positiveLeads - conversions - rates SmtpBreakdownView: type: object properties: accountId: type: string example: a7f1c2d4-... email: type: string example: outreach@acme.com nullable: true description: Sending account address. null when the account name is unavailable. totals: $ref: '#/components/schemas/BreakdownTotalsView' required: - accountId - email - totals SequenceBreakdownView: type: object properties: step: type: number example: 1 description: Sequence step number. variant: type: string example: A description: A/B variant letter. totals: $ref: '#/components/schemas/BreakdownTotalsView' required: - step - variant - totals BounceBreakdownView: type: object properties: total: type: number example: 14 hard: type: number example: 9 description: >- Permanent failures (5xx) – the address is bad; drop it from the list. soft: type: number example: 5 description: Temporary failures (4xx) – mailbox full, greylisting, throttling. senderBounces: type: number example: 3 description: Bounces caused by the sender side (reputation, auth, content). recipientBounces: type: number example: 11 description: >- Bounces caused by the recipient side (bad address, disabled mailbox). unknownBounces: type: number example: 0 description: Bounces we could not attribute to either side. byCategory: type: array items: $ref: '#/components/schemas/BounceCategoryView' required: - total - hard - soft - senderBounces - recipientBounces - unknownBounces - byCategory ApiErrorBodyDto: type: object properties: type: type: string example: authorization_error description: Broad error class. code: type: string example: permission_denied description: Stable machine-readable code to switch on. message: type: string example: This API key is missing the required scope. status: type: number example: 403 requestId: type: string example: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f description: Correlation id - quote it in support requests. details: description: Field-level validation messages (present on validation errors). example: - name should not be empty type: array items: type: string retryAfter: type: number description: Seconds to wait before retrying (present on 429 responses). example: 30 required: - type - code - message - status - requestId EngagementCountView: type: object properties: total: type: number example: 240 description: >- Opens/clicks counted per email (bots excluded): the same email opened twice counts once, two different steps count twice. uniqueLeads: type: number example: 180 description: Distinct leads who did this at least once. required: - total - uniqueLeads AnalyticsRatesView: type: object properties: open: type: number example: 42.5 nullable: true description: uniqueLeads opened / leads contacted. click: type: number example: 8.1 nullable: true description: uniqueLeads clicked / leads contacted. reply: type: number example: 4.2 nullable: true description: uniqueLeads replied / leads contacted. bounce: type: number example: 1.9 nullable: true description: bounces / sent. delivery: type: number example: 98.1 nullable: true description: delivered / sent. unsubscribe: type: number example: 0.4 nullable: true description: unsubscribes / sent. conversion: type: number example: 2 nullable: true description: conversions / leads contacted. required: - open - click - reply - bounce - delivery - unsubscribe - conversion BreakdownTotalsView: type: object properties: sent: type: number example: 400 delivered: type: number example: 396 opens: $ref: '#/components/schemas/EngagementCountView' clicks: $ref: '#/components/schemas/EngagementCountView' replies: type: number example: 12 description: Distinct leads who replied. bounces: type: number example: 4 positiveLeads: type: number example: 3 description: >- Leads currently in a positive state (interested / meeting / converted). conversions: type: number example: 2 description: Conversions attributed to this row. conversionValue: type: number example: 6000 nullable: true description: Total value of those conversions, in your workspace currency. rates: $ref: '#/components/schemas/BreakdownRatesView' required: - sent - delivered - opens - clicks - replies - bounces - positiveLeads - conversions - rates BounceCategoryView: type: object properties: category: type: string example: invalid-mailbox description: Machine-readable category. label: type: string example: Invalid mailbox description: Human-readable label. type: type: string example: recipient enum: - sender - recipient - unknown description: >- Who is responsible: sender (reputation/auth/content – fix your sending), recipient (bad address – clean your list), or unknown. count: type: number example: 9 description: Unique messages that ended in this category. percentage: type: number example: 64.3 description: Share of all bounces, percent. Category counts sum to `total`. required: - category - label - type - count - percentage BreakdownRatesView: type: object properties: open: type: number example: 42.5 nullable: true click: type: number example: 8.1 nullable: true reply: type: number example: 4.2 nullable: true bounce: type: number example: 1.9 nullable: true delivery: type: number example: 98.1 nullable: true positive: type: number example: 2 nullable: true description: positiveLeads / leads contacted. conversion: type: number example: 1.5 nullable: true description: conversions / leads contacted. required: - open - click - reply - bounce - delivery - positive - conversion securitySchemes: ApiKey: scheme: bearer bearerFormat: mb_live_… type: http ```` ## Related topics - [Analytics](/analytics.md) - [Campaign analytics over time](/api-reference/analytics/campaign-analytics-over-time.md) - [Workspace analytics roll-up](/api-reference/analytics/workspace-analytics-roll-up.md) - [Campaign send status](/api-reference/campaigns/campaign-send-status.md) - [Authentication](/authentication.md)