> ## Documentation Index > Fetch the complete documentation index at: https://docs.tied.com/llms.txt > Use this file to discover all available pages before exploring further. # Batch analytics metrics > Authenticated account members only; administrators or a custom role with report_manage may read metrics and benchmarks. Ordinary agents/managers get 403; foreign or nonexistent accounts get 401. Reads are scoped through Current.account. At most 25 distinct ids. HTTP 200 contains metrics keyed by requested id, including partial failures: per-item 404 unknown metric, 422 invalid dimensions/grain, 503 unavailable, or 500 unexpected failure. Malformed shared dates/fields, duplicate ids and invalid list shapes fail the entire request with 422. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/accounts/{account_id}/analytics/metrics/batch openapi: 3.0.4 info: title: Tied API description: >- The Tied REST API. Three families of endpoint, each with its own credential: **Application** for everything inside an account, **Platform** for provisioning accounts and users, and **Client** for acting as a contact from your own surface. version: 1.1.0 termsOfService: https://tied.com/legal contact: email: hello@tied.com license: name: MIT License url: https://opensource.org/licenses/MIT servers: - url: https://app.tied.com description: Tied cloud security: [] tags: - name: Account AgentBots description: Account-specific Agent Bots - name: Agents description: Agent management APIs - name: Canned Responses description: Pre-defined responses for common queries - name: Contacts description: Contact management APIs - name: Contact Labels description: Manage contact labels - name: Conversation Assignments description: Manage conversation assignments - name: Conversation Labels description: Manage conversation labels - name: Conversations description: Conversation management APIs - name: Custom Attributes description: Custom fields for contacts and conversations - name: Custom Filters description: Saved filters for conversations - name: Inboxes description: Communication channels setup - name: Integrations description: Third-party integrations - name: Messages description: Message management APIs - name: Profile description: User profile APIs - name: Reports description: Analytics and reporting APIs - name: Teams description: Team management APIs - name: Webhooks description: Event notification webhooks - name: Automation Rule description: Workflow automation rules - name: Help Center description: Knowledge base management - name: Contacts API description: Public contact APIs - name: Conversations API description: Public conversation APIs - name: Messages API description: Public message APIs - name: CSAT Survey Page description: Customer satisfaction survey - name: Account description: >- The authenticated user's own account — read and update account settings. Distinct from the Platform family's **Accounts**, which provisions accounts across an installation. - name: Audit Logs description: Read the account's audit trail - name: Inbox API description: Public inbox lookup by channel identifier - name: Labels description: >- Create and manage the account's labels. Applying one to a conversation or contact is a separate endpoint under those resources. - name: Macros description: >- Saved multi-step actions an agent — or an integration — can run against one or more conversations. - name: Campaigns description: Ongoing website campaigns and one-off SMS and WhatsApp sends. - name: Contact Notes description: Internal notes on a contact. Never visible to the contact. - name: Help Center Categories description: Categories group a portal's articles, one tree per allowed locale. - name: Help Center Articles description: The articles a portal publishes, and their draft and archived states. - name: Summary Reports description: Per-agent, per-team, per-inbox and per-label totals for a period, as JSON. - name: Live Reports description: Right-now queue counts. No date range — these describe the present. - name: CSAT description: >- The satisfaction ratings contacts have submitted, and the metrics computed from them. - name: Notifications description: >- The per-user notification feed, its read and snooze state, and the settings that decide what lands in it. - name: Conversation Participants description: >- The agents watching a conversation. Participants get notified about it without being assigned to it. - name: Draft Messages description: >- The unsent reply held for a conversation. Stored in Redis, one per conversation. - name: Search description: >- One search service across conversations, contacts, messages and Help Center articles. - name: Dashboard Apps description: Embedded pages that appear as a tab beside a conversation. - name: Assignment Policies description: How conversations are handed out, and which inbox uses which policy. - name: Files description: Storing a file so another endpoint can attach it. - name: Bot Flows description: >- Scripted conversation flows, their versions, and the publish and rollback that move between them. - name: Billing description: >- Credit balance, usage, invoices, spend controls and the provider-hosted payment flows. - name: AMB Templates description: >- Saved Apple Messages primitive payloads an agent can reuse from the composer. - name: AMB Onboarding description: The in-flight Apple Messages for Business registration for an account. - name: Widget Session description: Starting a widget session and reading the visitor it belongs to. - name: Widget Conversation description: The visitor's conversation and its messages. - name: Widget Context description: Campaigns, agents, labels, events and uploads for a widget session. - name: CSAT Survey description: The public, unauthenticated survey a contact answers from a link. - name: Workspace description: Scheduling and cancelling deletion of the whole workspace. - name: Widget Integrations description: Provider actions available to a visitor session in its own conversation. - name: Orchestration Studio description: >- Administrator-only read APIs for Orchestration Studio cases and knowledge sources. - name: Topic Analytics description: Account Topics readiness, labeling health and usage aggregates. - name: Analytics V2 description: >- Account-scoped metrics, anonymized benchmarks and audited conversation drilldown. paths: /api/v2/accounts/{account_id}/analytics/metrics/batch: parameters: - $ref: '#/components/parameters/account_id' post: tags: - Analytics V2 summary: Batch analytics metrics description: >- Authenticated account members only; administrators or a custom role with report_manage may read metrics and benchmarks. Ordinary agents/managers get 403; foreign or nonexistent accounts get 401. Reads are scoped through Current.account. At most 25 distinct ids. HTTP 200 contains metrics keyed by requested id, including partial failures: per-item 404 unknown metric, 422 invalid dimensions/grain, 503 unavailable, or 500 unexpected failure. Malformed shared dates/fields, duplicate ids and invalid list shapes fail the entire request with 422. operationId: batch-analytics-v2-metrics requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/analytics_v2_batch_request' example: since: '2026-10-01' until: '2026-10-07' metrics: - id: conversation_volume dimensions: - time - id: unknown_metric responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/analytics_v2_batch' example: metrics: conversation_volume: metricId: conversation_volume unit: count pending: false lockOnBillingClose: false value: 3 delta: 0 spark: - 3 - 0 - 0 - 0 - 0 - 0 - 0 - 0 - 0 - 0 - 0 - 0 series: categories: - '1' - '2' - '3' - '4' - '5' - '6' - '7' categoryDates: - '2026-10-01' - '2026-10-02' - '2026-10-03' - '2026-10-04' - '2026-10-05' - '2026-10-06' - '2026-10-07' data: - 0 - 0 - 0 - 0 - 0 - 0 - 0 unknown_metric: error: status: 404 message: Unknown metric x-example-provenance: capture_file: >- docs/platform-api/analytics-v2-evidence/batch-analytics-v2-metrics-default.json content_type: application/json; charset=utf-8 synthetic: true scrubbed: true '400': description: >- The request presented both a Devise Token Auth session credential and an api_access_token. The request is refused before the action runs. content: application/json: schema: type: object required: - error properties: error: type: object required: - code properties: code: type: string enum: - multiple_credentials additionalProperties: false additionalProperties: false '401': description: >- Unauthenticated or account is not accessible to the caller. Devise authentication responses may use an `errors` array; account access denials use `error`. content: application/json: schema: oneOf: - $ref: '#/components/schemas/error_message' - type: object required: - errors properties: errors: type: array items: type: string '403': description: >- The role or AnalyticsDrilldownGuard refuses the caller; no conversation content is returned. content: application/json: schema: $ref: '#/components/schemas/error_message' '422': description: Malformed or unsupported input. content: application/json: schema: $ref: '#/components/schemas/error_message' '429': description: >- Account analytics budget exhausted. Retry-After is seconds until reset. headers: Retry-After: schema: type: string pattern: ^[0-9]+$ description: Seconds until reset. content: application/json: schema: type: object required: - error - retryAfter properties: error: type: string description: Rate-limit message. retryAfter: type: integer description: Seconds until retry. additionalProperties: false '503': description: >- Analytics or durable audit is unavailable. Drilldown fails closed without personal data. content: application/json: schema: $ref: '#/components/schemas/error_message' security: - userApiKey: [] components: parameters: account_id: in: path name: id schema: type: integer required: true description: The numeric ID of the account schemas: analytics_v2_batch_request: type: object required: - metrics properties: since: type: string description: Inclusive start date; default is 29 days before until. format: date until: type: string description: >- Inclusive last date; defaults to today in timezone. Maximum range 366 days and 800 buckets. format: date granularity: type: string description: >- Must be supported by each metric; defaults to day if supported, otherwise its first grain. enum: - hour - day - week - month timezone: type: string description: IANA time zone; default UTC. business_hours: type: boolean description: Legacy basis flag, mutually exclusive with hours. hours: type: string description: >- Hours basis; business/off require analytics_business_hours. Mutually exclusive with business_hours. enum: - all - business - 'off' compare: type: boolean description: Include aligned prior-window comparisons when supported. topic_mentions: type: string description: Count main topic only (default) or all topic mentions. enum: - main - all metrics: type: array description: >- Unique metric ids, 1–25 entries. Shared malformed fields fail the whole request; metric-specific errors affect that entry only. items: type: object required: - id properties: id: type: string description: >- Registry metric id; unknown ids are accepted and reported as a per-item 404. dimensions: type: array description: >- Metric-specific declared and currently served dimensions; time is implicit. items: type: string additionalProperties: false minItems: 1 maxItems: 25 analytics_v2_batch: type: object required: - metrics properties: metrics: type: object description: >- One entry keyed by each requested id, including unknown ids. Successful, pending and failed entries may coexist. additionalProperties: oneOf: - $ref: '#/components/schemas/analytics_v2_metric' - $ref: '#/components/schemas/analytics_v2_item_error' additionalProperties: false error_message: type: object description: >- The shape returned by `render_unauthorized`, `render_not_found_error` and `render_could_not_create_error`. properties: error: type: string description: A single human-readable message. example: Resource could not be found required: - error analytics_v2_metric: oneOf: - type: object required: - metricId - unit - pending - lockOnBillingClose properties: metricId: $ref: '#/components/schemas/analytics_v2_metric_id' unit: type: string description: Registry unit. enum: - count - rate - duration - percentile pending: type: boolean description: No sourced payload. enum: - true lockOnBillingClose: type: boolean description: >- Registry metadata only; this field does not enforce freezing at billing close. additionalProperties: false - type: object required: - metricId - unit - pending - lockOnBillingClose properties: metricId: $ref: '#/components/schemas/analytics_v2_metric_id' unit: type: string description: Registry unit. enum: - count - rate - duration - percentile pending: type: boolean description: Sourced metric payload follows. enum: - false lockOnBillingClose: type: boolean description: >- Registry metadata only; this field does not enforce freezing at billing close. value: description: >- Metric-specific scalar: counts/rates are numeric; duration values may be formatted strings; unavailable values are null. oneOf: - type: number nullable: true - type: string delta: type: number description: >- Percent change or percentage point change, according to the metric; null without a comparable prior value. nullable: true spark: type: array description: Metric sparkline values. items: type: number nullable: true series: type: object required: - categories - categoryDates properties: categories: type: array description: Display bucket labels. items: type: string categoryDates: type: array description: Underlying bucket dates or hourly instants. items: type: string data: type: array description: Values aligned with bucket dates. items: type: number nullable: true compareData: type: array description: Prior-window values when compare is requested. items: type: number nullable: true description: series description: >- Pending envelope or sourced metric-specific payload. Payload definitions remain owned by Analytics (I-28); fields vary by metric, dimensions and grain. analytics_v2_item_error: type: object required: - error properties: error: type: object required: - status - message properties: status: type: integer description: Per-item status; HTTP remains 200. enum: - 404 - 422 - 500 - 503 message: type: string description: Safe failure summary. additionalProperties: false description: error additionalProperties: false analytics_v2_metric_id: type: string description: >- Generated from every metric id in config/analytics/semantic_model.yml. Regenerate with docs/tools/generate_analytics_metric_enum.py; unknown route ids return 404. enum: - resolution_volume - resolution_volume_by_class - resolution_volume_by_channel - resolver_split - time_to_resolution - signal_tier_mix - confirmed_resolution_rate - deflection_rate - automation_rate - escalation_rate - modifier_rate - void_rate - message_volume_by_channel - segment_usage - primitive_type_volume - delivery_rate - engagement_rate - quick_reply_taps - read_receipt_rate - voice_minutes - flow_completion_rate - usage_by_period - meter_reconciliation - conversion_volume - value_signal_volume - save_flow_success_rate - upsell_close_rate - attributed_conversion_volume - conversion_funnel - interaction_path_volume - rich_link_conversion_rate - sla_adherence - agent_resolutions - conversation_volume - first_response_time - reply_time - csat_positive_rate - csat_response_rate - bot_handoff_count - handle_time - agent_learning_activity - time_to_human - sentiment_score - positive_message_rate - negative_message_rate - at_risk_conversations - topic_volume - topic_share - topic_share_change - topic_coverage - topic_table securitySchemes: userApiKey: type: apiKey in: header name: api_access_token description: >- This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.