Provide usage data to Agora

Before publishing your extension in the Agora Extension Marketplace, you need to implement the usage and billing API and provide the URLs to Agora. Agora calls this API regularly to get the usage and billing information of a specified user in order to notify the user in Agora Console.

This page provides a detailed description of the usage and billing API.

Requirements

Before implementing the usage and billing API, ensure that your server meets the following requirements:

• Able to handle at least 100 requests per second.
• Follows the standards of HTTP request and response.

Agora waits for 500 millseconds after sending a request to your server. If a timeout occurs, Agora resends the request for a maximum of two times.

Usage

After a user adds an extension in their Agora projects, Agora sends this request every day. After receiving your response, Agora adds up the total amount of the usage, rounds it up, and updates the usage information on Agora Console.

HTTP request

URL

GET https://{host}/usage?fromTs={ts}&toTs={ts}&pageNum={pageNum}&apiKey={apiKey}&signature={signature}

Query parameter

HTTP response

The response body contains the following fields:

Example

Request header

GET https://api.agora.io/usage?fromTs=1619913600&toTs=1619917200&pageNum=1&apiKey=pz*************gd&signature=SF*************3D HTTP/1.1

Response body

{
    "status": 0,
    "statusReason": "Success getting usage data",
    "data": {
        "totalSize": 2,
        "pageNum": 2,
        "hasNext": false,
        "data": [
            {
                "projectId": "4****2",
                "amount": 1,
                "description": "1 Minute × Agora_Marketplace_Pricing (Tier 1 at $*** / month)"
            }
        ]
    }
}

Billing

After a user adds an extension in their Agora projects, Agora sends this request at the end of each month to request the billing information. After receiving your response, Agora rounds the amount up and shows it on Agora Console.

HTTP request

URL

GET https://{host}/bill?fromTs={ts}&toTs={ts}&pageNum={pageNum}&apiKey={apiKey}&signature={signature}

Query parameter

HTTP Response

The response body contains the following fields:

Example

Request header

GET https://api.agora.io/usage?fromTs=1619913600&toTs=1619917200&pageNum=1&apiKey=pz*************gd&signature=SF*************3D HTTP/1.1

Response body

{
    "status": 0,
    "statusReason": "Success getting billing data",
    "data": {
        "totalSize": 2,
        "pageNum": 2,
        "hasNext": false,
        "data": [
            {
                "projectId": "4****2",
                "amount": 1,
                "description": "1 Minute × Agora_Marketplace_Pricing (Tier 1 at $*** / month)"
            }
        ]
    }
}

License

This API only applies to vendors that charge users with licenses.

Agora calls this API to retrieve the license information of a specified user, including the expiration time of the license.

HTTP request

URL

GET https://{host}/customers/{customerId}/license?apiKey={apiKey}&signature={signature}

Path parameter

customerId: The account ID of the user on Agora Console.

Query parameter

HTTP response

The response body contains the following fields:

Example

Request header

GET https://api.agora.io/customers/1234567/license?apiKey=pz*************gd&signature=SF*************3D HTTP/1.1

Response body

{
    "status": "success",
    "statusReason": "",
    "data": {
        "expireDate": "2025-10-01",
        "residueCount": "100"
    }
}