# Provide usage data to Agora (/en/realtime-media/marketplace/build/connect-to-agora-services/usage) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 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 [#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 [#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 [#http-request] **URL** ```bash 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](./signature-algorithm). You need to deploy the algorithm to verify that the request is sent by Agora. | ### HTTP response [#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 [#example] **Request header** ```bash GET https://api.agora.io/usage?fromTs=1619913600&toTs=1619917200&pageNum=1&apiKey=pz*************gd&signature=SF*************3D HTTP/1.1 ``` **Response body** ```json { "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 [#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 [#http-request-1] **URL** ```bash 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](./signature-algorithm). You need to deploy the algorithm to verify that the request is sent by Agora. | ### HTTP Response [#http-response-1] 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 [#example-1] **Request header** ```bash GET https://api.agora.io/usage?fromTs=1619913600&toTs=1619917200&pageNum=1&apiKey=pz*************gd&signature=SF*************3D HTTP/1.1 ``` **Response body** ```json { "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 [#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 [#http-request-2] **URL** ```bash 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](./signature-algorithm). You need to deploy the algorithm to verify that the request is sent by Agora. | ### HTTP response [#http-response-2] 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 [#example-2] **Request header** ```bash GET https://api.agora.io/customers/1234567/license?apiKey=pz*************gd&signature=SF*************3D HTTP/1.1 ``` **Response body** ```json { "status": "success", "statusReason": "", "data": { "expireDate": "2025-10-01", "residueCount": "100" } } ```