Get Organization Usage Summary

Retrieve the total credits consumption, new session count, and user query count of an organization over a time interval, and expand it by Agent / Workflow with pagination. A single call can obtain data for all Agents under the organization, without needing to call each Agent individually.

Note: You can query up to 31 days of data; only development spaces are counted. See "Statistical Scope" below for details.

Request Method

GET

Endpoint

https://api-${endpoint}.gptbots.ai/v1/org/stat/summary

Authentication

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 Owner and Administrators have it by default).
• Please call the address of the data center where the organization is located. ${endpoint} should be the region returned by Query Organization List (SG → sg, TH → th, JP → jp). Calls to other data centers will return "Not a member of this organization."

Call Frequency

• Each developer key can call this endpoint up to 60 times per minute.
• Each call also counts toward the organization plan's "Usage API" per-minute quota, shared with Agent API Key calls to usage APIs.
• Queries including today or yesterday are cached for 5 minutes; results for earlier dates are cached for 1 hour. It is recommended to call the API every 5 to 15 minutes.

Request

Request Example

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/stat/summary?org_id=${org_id}&start_time=1792425600000&end_time=1795017600000&page=1&page_size=20' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

                    

Request Headers

Request Parameters

Response

Response Example

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "org_id": "65f0c2a1b4e8d93a1c7e5b20",
        "timezone": "+07:00",
        "range_start_date": "2026-10-16",
        "range_end_date": "2026-11-14",
        "data_since": "2026-10-15",
        "data_until": 1794614400000,
        "total": {
            "credits": 1234.5678,
            "unattributed_credits": 36.2011,
            "conversation_count": 5210,
            "message_count": 48213
        },
        "agents": {
            "page": 1,
            "page_size": 20,
            "total": 86,
            "list": [
                {
                    "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
                    "name": "客服助手",
                    "agent_type": "AGENT",
                    "credits": 402.1200,
                    "conversation_count": 2104,
                    "message_count": 19820
                },
                {
                    "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                    "name": "订单查询",
                    "agent_type": "WORKFLOW",
                    "credits": 130.5000,
                    "conversation_count": null,
                    "message_count": null
                }
            ]
        }
    }
}

                    

Successful Response

Failed Response

Error Codes

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 Scope

• Scope of Statistics: Only statistics for the developer space, including API, shared pages, web embedding, bubble components, LiveDesk, as well as various instant messaging and phone channels, and the developer space's Workflow; usage in workspaces (GWork) is not included, nor is usage of published Agents within workspaces.
• Credits: All consumption types (excluding point expiration and subscription payments). Workflow consumption is recorded under the Workflow itself; consumption generated by an Agent calling a Workflow is not counted for that Agent. Credits data is available from the feature launch date (data_since) and historical data is not backfilled.
• Number of Sessions: The number of sessions created within the period that have had at least one conversation, excluding developer space debug previews. Workflow runs do not generate sessions; AI searches in workspaces are not counted. Session and question counts have data starting from 31 days before the feature launch.
• Number of Questions: The number of question messages sent by users within the period, excluding AI replies.
• Sorting: agents.list is sorted by credits in descending order; if credits are the same, sorted by number of sessions. Agents with no credits, sessions, or questions in the period will not be listed.
• Update Frequency: Credits are updated in real time; session and question counts are updated every hour on the hour, with approximately a 1-hour delay.