> ## 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 over time > One point per interval so you can chart a campaign – this series carries bounces AND unsubscribes, so those rates are chartable without extra calls. Long windows auto-coarsen (day → week → month); the response says which interval it used. Requires one of the following scopes: `metrics:read`, `all:read`, `all:all`. ## OpenAPI ````yaml /openapi.json get /v1/campaigns/{id}/analytics/timeseries 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/timeseries: get: tags: - Analytics summary: Campaign analytics over time description: >- One point per interval so you can chart a campaign – this series carries bounces AND unsubscribes, so those rates are chartable without extra calls. Long windows auto-coarsen (day → week → month); the response says which interval it used. Requires one of the following scopes: `metrics:read`, `all:read`, `all:all`. operationId: analytics_getCampaignTimeseries 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: interval required: false in: query description: >- Bucket size. Coarser intervals are auto-selected for long windows to keep the series readable. schema: default: day example: day type: string enum: - day - week - month responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/AnalyticsTimeseriesApiResponseDto' '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: AnalyticsTimeseriesApiResponseDto: type: object properties: campaignId: type: string example: c1a2b3d4-... period: $ref: '#/components/schemas/AnalyticsPeriodView' interval: type: string example: day enum: - day - week - month description: >- Bucket size actually used – may be coarser than requested for long windows. data: type: array items: $ref: '#/components/schemas/AnalyticsTimeseriesPointView' required: - campaignId - period - interval - data 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 AnalyticsTimeseriesPointView: type: object properties: timestamp: type: string example: '2026-06-14T00:00:00.000Z' description: Start of the bucket. sent: type: number example: 120 delivered: type: number example: 118 opens: $ref: '#/components/schemas/EngagementCountView' clicks: $ref: '#/components/schemas/EngagementCountView' replies: type: number example: 4 bounces: type: number example: 2 unsubscribed: type: number example: 1 description: Unsubscribes in this bucket. required: - timestamp - sent - delivered - opens - clicks - replies - bounces - unsubscribed 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 securitySchemes: ApiKey: scheme: bearer bearerFormat: mb_live_… type: http ```` ## Related topics - [Analytics](/analytics.md) - [Campaign analytics](/api-reference/analytics/campaign-analytics.md) - [Workspace analytics roll-up](/api-reference/analytics/workspace-analytics-roll-up.md) - [Campaigns](/campaigns.md) - [Overview](/introduction.md)