Get Agent Escalation Rate

Retrieve the number of sessions, the number of sessions escalated to human agents, and the escalation rate for a specific Agent within a time period. The methodology is consistent with the console's "Agent Insights → Escalation Rate".

Note: You can query up to 92 days of data; only channels in the development workspace are included. For the statistical scope, see "Statistical Methodology" below.

Request Method

GET

API Endpoint

https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/human-handoff

Authentication

Use Basic authentication with an account-level DevKey / DevSecret: Authorization: Basic ${BASIC_TOKEN}, where ${BASIC_TOKEN} is the Base64 encoding of DevKey:DevSecret.

• The calling account must be a member of the organization corresponding to org_id and have "View Usage" permissions (Owners and Admins have it by default), and must be able to access the Agent: the Agent creator, the organization Owner, or members granted permissions for this Agent (or all Agents).
• Please call the endpoint in the data center where your organization is located. ${endpoint} should be set to the region returned by Query Organization List (SG → sg, TH → th, JP → jp). Calling from another data center will return "Not a member of this organization".

Rate Limit

• Each developer key can call this API up to 60 times per minute.
• Each call counts toward the organization's package "Statistics API" per-minute quota, shared with Agent API Key calls to statistics APIs.
• Query results are cached for 10 minutes. It is recommended to call once per hour.

Request

Request Example

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/human-handoff?org_id=${org_id}&agent_id=${agent_id}&start_time=1788192000000&end_time=1790784000000' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

                    

Request Header

Request Parameters

Response

Response Example

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
        "timezone": "+08:00",
        "range_start_date": "2026-09-01",
        "range_end_date": "2026-09-29",
        "data_until": 1790665200000,
        "conversation_count": 1200,
        "handoff_conversation_count": 96,
        "handoff_rate": 0.0800
    }
}

                    

Successful Response

Failed Response

Error Codes

The HTTP status code corresponds to the first three digits of the error code, for example, 40000 corresponds to 400, 40100 corresponds to 401, 403132 corresponds to 403.

Statistical Caliber

• Number of sessions: The number of sessions that had conversations each day, accumulated daily; sessions that continue across days are counted once for each day.
• Number of human-transferred sessions: The number of sessions that were transferred to a human agent.
• Statistical scope: Only counts channels in the development space, including API, share pages, web embeds, bubble components, LiveDesk, and various instant messaging and phone channels; does not include usage after the Agent is published to a workspace.
• Update frequency: Dates with completed daily statistics read daily statistics; calculated in real-time for the current day. Daily statistics are generated by the statistical task after midnight in the organization’s time zone. Before generation is complete, the previous day is also calculated in real-time, so there will not be a situation where "yesterday" after midnight is 0.
• Caliber of real-time part: Counted based on the time of the latest conversation of the session. Sessions that continue across days are only counted once in the real-time part (counted on the day of the latest conversation), which may have slight differences from the daily statistics accumulated by day.