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

Parameter	Required/Optional	Type	Data length	Description
`fromTs`	Required	Timestamp	10	The start point of the time range to query usage data, which must be later than 00:00:00 (UTC) on the day.
`toTs`	Required	Timestamp	10	The end point of the time range to query usage data, which must be earlier than 23:59:59 (UTC) on the day.
`pageNum`	Required	Number	N/A	The page number of the usage list. You need to implement pagination to the usage list and return the `hasNext` field in the response. Agora always sets this parameter as one at the first request every day and repeats requesting until `hasNext` in the response returns `false`.
`limit`	Optional	Number	N/A	The number of data entries in the response. Ensure that you set a default value to this parameter.
`apiKey`	Required	String	32	The API key, used for authentication between you and Agora. When you register as a vendor on Agora Console, Agora generates an API key as the identifier.
`signature`	Required	String	N/A	The signature generated by the signature algorithm. You need to deploy the algorithm to verify that the request is sent by Agora.

HTTP response

The response body contains the following fields:

Field	Type	Description
`status`	Number	The status code. `0` means that the request succeeds.
`statusReason`	String	The reason for the status.
`totalSize`	Number	The total number of the user's Agora projects where your extension is added.
`pageNum`	Number	The page number of the usage list. This parameter should be the same with the `pageNum` field in the request.
`hasNext`	Boolean	Whether the usage page list has the next page: `true`: The usage page list has the next page. The request repeats. `false`: The usage page list does not have the next page. The request stops.
`data`	Array	The usage data, which contains the following properties: `projectId`: The project ID. `amount`: The usage amount. The data format is BigDecimal. The unit of measurement is as follows: If usage is measured in duration, the default unit is minute. If usage is measured in the amount of times, the default unit is times. If you need a custom unit of measurement, contact your account manager. `description`: The detailed description of the usage amount. Return the usage data only when `projectId` is not empty and `amount` is not zero.

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

Parameter	Required/Optional	Type	Data length	Description
`fromTs`	Required	Timestamp	10	The start point of the time range to query billing data, which must be later than 00:00:00 (UTC) on the first day of the month.
`toTs`	Required	Timestamp	10	The end point of the time range to query billing data, which must be earlier than 23:59:59 (UTC) on the last day of the month.
`pageNum`	Required	Number	N/A	The page number of the billing list.You need to implement pagination to the billing list and return the `hasNext` field in the response. Agora always sets this parameter as one at the first request every month and repeats requesting until `hasNext` in the response returns false.
`limit`	Optional	Number	N/A	The number of data entries in the response. Ensure that you set a default value to this parameter.
`apiKey`	Required	String	32	The API key, used for authentication between you and Agora. When you register as a vendor on Agora Console, Agora generates an API key as the identifier.
`signature`	Required	String	N/A	The signature generated by the signature algorithm. You need to deploy the algorithm to verify that the request is sent by Agora.

HTTP Response

The response body contains the following fields:

Field	Type	Description
`status`	Number	The status code. `0` means that the request succeeds.
`statusReason`	String	The reason for the status.
`totalSize`	Number	The total number of the user's Agora projects where your extension is added.
`pageNum`	Number	The page number of the billing list. This parameter should be the same with the `pageNum` field in the request.
`hasNext`	Boolean	Whether the billing page list has the next page: `true`: The billing page list has the next page. The request repeats. `false`: The billing page list does not have the next page. The request stops.
`data`	Array	The billing data, which contains the following properties: `projectId`: The project ID. `amount`: The billing amount. The data format is BigDecimal. The unit of measurement is set with the configuration with Agora. To change the unit of measurement, contact your account manager. `description`: The detailed description of the billing amount. Return the billing data only when `projectId` is not empty and `amount` is not zero.

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

Parameter	Required/Optional	Type	Data length	Description
`apiKey`	Required	String	32	The API key, used for authentication between you and Agora. When you register as a vendor on Agora Console, Agora generates an API key as the identifier.
`signature`	Required	String	N/A	The signature generated by the signature algorithm. You need to deploy the algorithm to verify that the request is sent by Agora.

HTTP response

The response body contains the following fields:

Field	Type	Description
`status`	String	The status of the request: `success`: The request succeeds. `failed`: The request fails.
`statusReason`	String	The reason for the status.
`expireDate`	String	The expiration time of the license.
`residueCount`	String	The remaining amount of usage covered by the license.

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"
    }
}