Retrieve Recent Activity of Agents

Retrieve the number of new sessions and user inquiries for one or more Agents in the last N minutes, suitable for periodic activity checks. You can query up to 50 Agents at a time.

Request Method

GET

Endpoint

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

Authorization

Use account-level DevKey / DevSecret with Basic authentication: 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 "Usage View" permission (organization Owners and admins have this permission by default), and must also be able to access the Agent: the Agent creator, the organization Owner, or members granted permission for this Agent (or all Agents).
Please call the endpoint in the data center where the organization is located. ${endpoint} takes the value region returned from Query Organization List (SG → sg, TH → th, JP → jp). Calling other data centers will return "Not a member of this organization."

Call Frequency

Each developer key can call this API up to 60 times per minute.
Each call counts towards the organization plan's "Statistics API" per-minute quota, shared with Agent API Key for statistical interface calls.
Query results are cached for 30 seconds. It is recommended to call once per minute and combine multiple Agents into a single request.

Request

Request Example

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity?org_id=${org_id}&agent_id=${agent_id_1},${agent_id_2}&minutes=5' \ -H 'Authorization: Basic ${BASIC_TOKEN}'

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity?org_id=${org_id}&agent_id=${agent_id_1},${agent_id_2}&minutes=5' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

此代码块在浮窗中显示

Request Headers

Field	Type	Description
Authorization	Basic ${BASIC_TOKEN}	Basic Token after `DevKey:DevSecret` Base64 encoding.

Request Parameters

Field	Type	Required	Description
org_id	String	Yes	Organization ID.
agent_id	String	Yes	Agent ID, separated by commas, up to 50, duplicates count only once. Workflow not supported.
minutes	Integer	No	Number of minutes to count, from 1 to 60, default is 5.

Response

Response Example

{ "code": 0, "message": "OK", "data": { "minutes": 5, "window_start": 1790664900000, "window_end": 1790665200000, "agents": [ { "agent_id": "65f0c2a1b4e8d93a1c7e5b21", "new_conversation_count": 3, "new_message_count": 27 } ] } }

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "minutes": 5,
        "window_start": 1790664900000,
        "window_end": 1790665200000,
        "agents": [
            {
                "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
                "new_conversation_count": 3,
                "new_message_count": 27
            }
        ]
    }
}

此代码块在浮窗中显示

Successful Response

Field	Type	Description
minutes	Integer	Length of the statistical window (minutes).
window_start	Long	Window start (timestamp in milliseconds).
window_end	Long	Window end (timestamp in milliseconds, exclusive).
agents[].agent_id	String	Agent ID, in the same order as `agent_id` in the request.
agents[].new_conversation_count	Long	Number of new conversations in the window that have already had at least one interaction.
agents[].new_message_count	Long	Number of user questions sent in the window, excluding AI replies.

Failed Response

Field	Type	Description
code	Integer	Error code.
message	String	Error details.

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.

Error Code	Description
40000	Parameter error, such as missing required parameters or invalid parameter values.
40001	Too frequent calls: The developer key exceeds the per-minute limit for this API.
40008	Exceeds the per-minute quota of the organization's package for 'statistical APIs'.
40010	API temporarily closed, please try again later.
40100	No permission: Missing usage view permission or no right to view this Agent (including the Agent not belonging to the organization).
40105	Not a member of this organization, or called an address from another data center.
40324	DevKey or DevSecret error.
40378	Agent has been deleted.
403132	Invalid time range: the start time is not earlier than the end time, or it exceeds the maximum query range.

Statistical Criteria

Both numbers matter: Conversations on instant messaging channels continue in the same session if there are no new messages within 60 minutes. Active channel agents may also have long periods without new sessions. Looking only at new session counts may misjudge them as inactive.
Scope of statistics: Only channels in the development space are counted, including API, share page, web embeds, bubble components, LiveDesk, as well as various instant messaging and phone channels; this does not include debug previews in the development space or the agent's usage in the workspace.
Update frequency: Calculated in real time.