Skip to main content
Android
iOS
Web
macOS
Windows
Flutter
React Native

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


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

Query parameter

ParameterRequired/OptionalTypeData lengthDescription
fromTsRequiredTimestamp10The start point of the time range to query usage data, which must be later than 00:00:00 (UTC) on the day.
toTsRequiredTimestamp10The end point of the time range to query usage data, which must be earlier than 23:59:59 (UTC) on the day.
pageNumRequiredNumberN/AThe 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.
limitOptionalNumberN/AThe number of data entries in the response. Ensure that you set a default value to this parameter.
apiKeyRequiredString32The 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.
signatureRequiredStringN/AThe 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:

FieldTypeDescription
statusNumberThe status code. 0 means that the request succeeds.
statusReasonStringThe reason for the status.
totalSizeNumberThe total number of the user's Agora projects where your extension is added.
pageNumNumberThe page number of the usage list. This parameter should be the same with the pageNum field in the request.
hasNextBooleanWhether 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.
  • dataArrayThe 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


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

    Response body


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

    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


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

    Query parameter

    ParameterRequired/OptionalTypeData lengthDescription
    fromTsRequiredTimestamp10The 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.
    toTsRequiredTimestamp10The 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.
    pageNumRequiredNumberN/AThe 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.
    limitOptionalNumberN/AThe number of data entries in the response. Ensure that you set a default value to this parameter.
    apiKeyRequiredString32The 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.
    signatureRequiredStringN/AThe 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:

    FieldTypeDescription
    statusNumberThe status code. 0 means that the request succeeds.
    statusReasonStringThe reason for the status.
    totalSizeNumberThe total number of the user's Agora projects where your extension is added.
    pageNumNumberThe page number of the billing list. This parameter should be the same with the pageNum field in the request.
    hasNextBooleanWhether 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.
  • dataArrayThe 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


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

    Response body


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

    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


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

    Path parameter

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

    Query parameter

    ParameterRequired/OptionalTypeData lengthDescription
    apiKeyRequiredString32The 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.
    signatureRequiredStringN/AThe 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:

    FieldTypeDescription
    statusStringThe status of the request:
  • success: The request succeeds.
  • failed: The request fails.
  • statusReasonStringThe reason for the status.
    expireDateStringThe expiration time of the license.
    residueCountStringThe remaining amount of usage covered by the license.

    Example

    Request header


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

    Response body


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

    vundefined