Hootsuite

Hootsuite Real Time Metrics Rest API

When calling the Real-time Metrics API, the client needs to be authenticated. The [REST API authentication](#tag/rest-api-authentication) section contains more details on how to authenticate your client.

GitHub OpenAPI

Operations 9

POST /inbox/v1/reporting/metrics/inbound-message-volume Inbound message volume #
POST /inbox/v1/reporting/metrics/outbound-message-volume Outbound message volume #
POST /inbox/v1/reporting/metrics/first-response-time Average first response time #
POST /inbox/v1/reporting/metrics/conversation-response-time Average conversation response time #
POST /inbox/v1/reporting/metrics/resolved-with-one-reply Resolved with reply #
POST /inbox/v1/reporting/metrics/handle-time Average handle time #
POST /inbox/v1/user-presence/metrics/agent-availability Agent availability #
POST /inbox/v1/queue/metrics/contacts-waiting Contacts waiting in queue #
POST /inbox/v1/queue/metrics/longest-wait-time Longest wait time in queue #

Documentation

📖
Documentation
https://developer.hootsuite.com/docs/api-overview
📖
APIReference
https://apidocs.hootsuite.com/docs/api/index.html
📖
GettingStarted
https://developer.hootsuite.com/docs/getting-started-with-the-rest-api
📖
Authentication
https://developer.hootsuite.com/docs/api-authentication
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/hootsuite/refs/heads/main/rate-limits/hootsuite-rate-limits.yml
📖
Documentation
https://developer.hootsuite.com/docs/analytics-overview
📖
APIReference
https://apidocs.hootsuite.com/docs/api/analytics/index.html
📖
GettingStarted
https://developer.hootsuite.com/docs/using-the-api
📖
Documentation
https://developer.hootsuite.com/docs/inbox-overview
📖
APIReference
https://apidocs.hootsuite.com/docs/api/inbox/index.html
📖
Documentation
https://developer.hootsuite.com/docs/amplify-overview
📖
APIReference
https://amplify.hootsuite.com/api-docs

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/hootsuite/refs/heads/main/openapi/hootsuite-real-time-metrics-rest-api-api-openapi.yml

Other Resources

🔗
OAuth 2.0
https://developer.hootsuite.com/docs/enabling-oauth-20
🔗
Postman
https://app.getpostman.com/run-collection/eeda0fcdf55ea26bd0ec
🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/hootsuite/refs/heads/main/asyncapi/hootsuite-webhooks.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/hootsuite/refs/heads/main/errors/hootsuite-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/hootsuite/refs/heads/main/data-model/hootsuite-data-model.yml
🔗
OAuthScopes
https://raw.githubusercontent.com/api-evangelist/hootsuite/refs/heads/main/scopes/hootsuite-scopes.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/hootsuite-real-time-metrics-rest-api-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

hootsuite-real-time-metrics-rest-api-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Inbox 2.0 API Reference Real Time Metrics Rest API
  description: Inbox 2.0 API Reference
  version: v1
  x-logo:
    url: static/hootsuite-logo.png
  contact:
    email: dev.support@hootsuite.com
  license:
    name: Hootsuite Developer Terms and API License Agreement
    url: https://hootsuite.com/legal/dev-api-terms
servers:
- url: https://platform.hootsuite.com
  description: Inbox 2.0 production server
security:
- bearer-token: []
tags:
- name: real_time_metrics_rest_api
  x-displayName: REST API
  description: 'When calling the Real-time Metrics API, the client needs to be authenticated.


    The [REST API authentication](#tag/rest-api-authentication) section contains more details on how to authenticate your client.

    '
paths:
  /inbox/v1/reporting/metrics/inbound-message-volume:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Inbound message volume
      operationId: metricsInboundMessageVolume
      description: 'A count of inbound messages based on applied filters.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotalMessagesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/TimeSeriesMetricResponse'
              examples:
                SingleValue:
                  value: 6
                GroupByInterval:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: 4
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/outbound-message-volume:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Outbound message volume
      operationId: metricsOutboundMessageVolume
      description: 'A count of outbound messages based on applied filters.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotalMessagesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/TimeSeriesMetricResponse'
              examples:
                SingleValue:
                  value: 6
                GroupByInterval:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: 4
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/first-response-time:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Average first response time
      operationId: metricsAverageFirstResponseTime
      description: 'The average time in seconds to the first response to an inbound message.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseTimeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
                - $ref: '#/components/schemas/TimeSeriesMetricResponse'
              examples:
                singleValue:
                  value: 6
                groupByTeam:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 4
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 2
                groupByDay:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: 4
                groupByDayAndTeam:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value:
                      c3144df7-8a04-4b20-b60a-ccfe97723780:
                        value: 4
                      3b48a76e-4289-44b8-ac15-c8b60d21f158:
                        value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: null
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/conversation-response-time:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Average conversation response time
      operationId: metricsAverageConversationResponseTime
      description: 'The average time in seconds for a response to an inbound message except the first response.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseTimeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
                - $ref: '#/components/schemas/TimeSeriesMetricResponse'
              examples:
                singleValue:
                  value: 6
                groupByTeam:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 4
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 2
                groupByDay:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: 4
                groupByDayAndTeam:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value:
                      c3144df7-8a04-4b20-b60a-ccfe97723780:
                        value: 4
                      3b48a76e-4289-44b8-ac15-c8b60d21f158:
                        value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: null
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/resolved-with-one-reply:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Resolved with reply
      operationId: metricsResolvedWithReply
      description: 'The number of messages that have been resolved with at least one reply.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotalResolvedConversationsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
              examples:
                singleValue:
                  value: 6
                groupByTeam:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 4
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 2
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/handle-time:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Average handle time
      operationId: metricsAverageHandleTime
      description: 'The average time in seconds that a conversation is handled by an agent, specifically the difference between timestamps

        of conversation open and conversation pend/resolve. For Average Handle Time to be calculated, there must be an outbound

        between open and pend/resolve event.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HandleTimeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberMetricResponse'
              examples:
                singleValue:
                  value: 6
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/user-presence/metrics/agent-availability:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Agent availability
      operationId: metricsAgentAvailability
      description: 'The number of agents available or away. You can filter by teams.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentAvailabilityRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberMetricResponse'
              example:
                value: 30
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/queue/metrics/contacts-waiting:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Contacts waiting in queue
      operationId: metricsContactsWaitingInQueue
      description: 'The number of contacts waiting in the queue for a response.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
              examples:
                singleValue:
                  value: 6
                groupByChannel:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 4
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 2
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/queue/metrics/longest-wait-time:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Longest wait time in queue
      operationId: metricsLongestWaitTimeInQueue
      description: 'The current longest time in seconds that a contact is waiting for a response. If no mediumId filter is provided, the

        messages sent in any connected mediums will be included.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
              examples:
                singleValue:
                  value: 131
                groupByChannel:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 131
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 155
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
components:
  schemas:
    GroupByInterval:
      type: string
      enum:
      - MINUTE
      - HOUR
      - DAY
      - MONTH
      - YEAR
      - HOUR_BY_DAY
      description: 'An interval to group results by. No more than 60 intervals can be requested per request. For example, when selecting `minute`, the requested time range cannot be longer than 1 hour

        '
    From:
      type: string
      description: 'An `ISO-8601` date time marking the inclusive start of the result. Must be URL encoded. The `from` filter can be a maximum of 14 days in the past.

        '
    ChannelId:
      type: string
      description: 'Filter by channel identifier (to obtain a list of your channel IDs, contact a Inbox 2.0 representative)

        '
    TotalResolvedConversationsRequest:
      type: object
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/From'
        to:
          $ref: '#/components/schemas/To'
        mediumIds:
          type: array
          items:
            $ref: '#/components/schemas/MediumId'
        channelIds:
          type: array
          items:
            $ref: '#/components/schemas/ChannelId'
        teamIds:
          type: array
          items:
            $ref: '#/components/schemas/TeamId'
        groupBy:
          type: string
          enum:
          - TEAM
    Timezone:
      type: string
      description: 'The `timezone` to be used in conjunction with`groupByInterval`, e.g. America/Los_Angeles. Must be URL encoded. If no `timezone` is provided, the default ''UTC'' timezone is used

        '
    AgentAvailabilityRequest:
      type: object
      properties:
        teamIds:
          type: array
          items:
            type: string
          description: 'Filter by teams

            '
        userPresenceStatus:
          type: string
          enum:
          - AWAY
          - AVAILABLE
    TotalMessagesRequest:
      type: object
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/From'
        to:
          $ref: '#/components/schemas/To'
        timezone:
          $ref: '#/components/schemas/Timezone'
        mediumIds:
          type: array
          items:
            $ref: '#/components/schemas/MediumId'
        channelIds:
          type: array
          items:
            $ref: '#/components/schemas/ChannelId'
        groupByInterval:
          $ref: '#/components/schemas/GroupByInterval'
    MetricRequest:
      type: object
      required:
      - status
      properties:
        channelIds:
          type: array
          items:
            type: string
        teamIds:
          type: array
          items:
            type: string
        mediumId:
          $ref: '#/components/schemas/MediumId'
        groupBy:
          type: string
          enum:
          - CHANNEL
          - OWNER
          - TOPIC
          - TEAM
        status:
          type: string
          enum:
          - NEW
          - PENDING
    UserId:
      type: string
      description: 'Filter by user identifier

        '
    MediumId:
      type: string
      enum:
      - fb
      - twit
      - instagram
      - rtm
      - whatsapp
      - linkedin
      description: 'Filter by medium identifier

        '
    ResponseTimeRequest:
      type: object
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/From'
        to:
          $ref: '#/components/schemas/To'
        timezone:
          $ref: '#/components/schemas/Timezone'
        mediumIds:
          type: array
          items:
            $ref: '#/components/schemas/MediumId'
        channelIds:
          type: array
          items:
            $ref: '#/components/schemas/ChannelId'
        teamIds:
          type: array
          items:
            $ref: '#/components/schemas/TeamId'
        groupByInterval:
          $ref: '#/components/schemas/GroupByInterval'
        groupBy:
          type: string
          enum:
          - TEAM
    TeamId:
      type: string
      description: 'Filter by team identifier

        '
    To:
      type: string
      description: 'An `ISO-8601` date time marking the exclusive end of the result. Must be URL encoded

        '
    TimeSeriesMetricResponse:
      type: object
      properties:
        value:
          type: array
          items:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/TimeSeriesDataPoint'
    TimeSeriesDataPoint:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        value:
          type: object
          oneOf:
          - $ref: '#/components/schemas/GroupedMetricResponse'
          - $ref: '#/components/schemas/NumberMetricResponse'
    HandleTimeRequest:
      type: object
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/From'
        to:
          $ref: '#/components/schemas/To'
        mediumIds:
          type: array
          items:
            $ref: '#/components/schemas/MediumId'
        channelIds:
          type: array
          items:
            $ref: '#/components/schemas/ChannelId'
        userIds:
          type: array
          items:
            $ref: '#/components/schemas/UserId'
        handleTimeTypes:
          type: array
          items:
            type: string
            enum:
            - HANDLE_TIME
            - NO_REPLY_TIME
            - CHERRY_PICKING
    GroupedMetricResponse:
      type: object
      properties:
        value:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/NumberMetricResponse'
    NumberMetricResponse:
      type: object
      properties:
        value:
          type: integer
  securitySchemes:
    bearer-token:
      type: http
      scheme: bearer
    basic-auth:
      type: http
      scheme: basic
    Oauth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: TO_BE_CONFIGURED_IN_INBOX_2_0
          scopes:
            some_scope: TO_BE_CONFIGURED_IN_INBOX_2_0
    SharedSecret:
      type: apiKey
      in: header
      name: X-Hootsuite-Signature
x-provenance:
  generated: '2026-08-13'
  method: searched
  source: https://apidocs.hootsuite.com/docs/api/inbox/openapi/openapi.yaml
  note: Verbatim first-party OpenAPI 3.1 for the Hootsuite Inbox 2.0 API (formerly Sparkcentral), linked as service-desc for anchor https://platform.hootsuite.com/inbox/v1/ in Hootsuite's RFC 9727 API catalog at https://www.hootsuite.com/.well-known/api-catalog.
  ownership: servers[] https://platform.hootsuite.com, contact dev.support@hootsuite.com, license "Hootsuite Developer Terms and API License Agreement" - Hootsuite's own contract.
x-tagGroups:
- name: General
  tags:
  - rest-api-authentication
- name: CRM API
  tags:
  - crm_introduction
  - crm_webhooks
  - crm_rest_api
- name: Virtual Agent API
  tags:
  - vai_introduction
  - vai_webhooks
  - vai_rest_api
- name: Real-time metrics API
  tags:
  - real_time_metrics_introduction
  - real_time_metrics_rest_api
- name: User Presence API
  tags:
  - user_presence_introduction
  - user_presence_rest_api
- name: Queue API
  tags:
  - queue_introduction
  - queue_rest_api
- name: Proactive messaging API
  tags:
  - proactive_messaging_introduction
  - proactive_messaging_rest_api
- name: Messenger SDK
  tags:
  - messenger_introduction
  - messenger_web_sdk