Obtain Organization Credit Usage Distribution

Get the proportion ranking of an organization’s credits or tokens by Agent/Workflow, as well as trends by day, week, or month. You can view only Agents or only Workflows.

Note: Data can be queried for up to 92 days; only development spaces are counted. The statistical scope is described below under "Statistical Criteria".

Request Method

GET

Call URL

https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution

Call 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 Owners and Administrators have it by default).
• Please call the address of the data center where the organization is located. ${endpoint} should be taken from region returned by 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 10 times per minute.
• Each call counts toward the organization’s package "Statistical API" per-minute quota and shares this quota with Agent API Key calls to statistical interfaces.
• Query results are cached for 10 minutes. It is recommended to call once per day.

Request

Request Example

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution?org_id=${org_id}&start_time=1792425600000&end_time=1792684800000&agent_type=WORKFLOW&granularity=DAY' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

                    

Request Headers

Request Parameters

Response

Response Example

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "timezone": "+07:00",
        "data_since": "2026-10-15",
        "buckets": ["2026-10-16", "2026-10-17", "2026-10-18"],
        "total": 812.4411,
        "series": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49,
                "points": [130.5000, 141.0200, 130.6000]
            },
            {
                "row_type": "OTHER",
                "agent_id": null,
                "name": null,
                "agent_type": null,
                "total": 410.3211,
                "share": 50.51,
                "points": [120.1000, 150.2000, 140.0211]
            }
        ],
        "ranking": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49
            }
        ]
    }
}

                    

Successful Response

Failure 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 Scope

• Scope of Statistics: Only counts the developer space, including API, share pages, web embedding, bubble components, LiveDesk, as well as various instant messaging and phone channels, and the developer space's Workflow; it does not include the usage of workspaces (GWork), nor does it include the parts of published Agents used within workspaces. Therefore, the total amount may be slightly lower than the same period shown on the console's "Organization → Usage" page.
• Credits: All types of consumption (excluding expired credits and subscription payments); workflow consumption is recorded under the workflow itself.
• Data Start Point: Available from the feature launch date (data_since), with no backfill of historical data.
• Update Frequency: Updated in real time.