Get Usage
This endpoint provides information about the plan and pack usage details for a particular group. It will give you information about the number of available resources (such as documents, pages, etc. – depending on what your plan(s)/packs(s) are configured with) for the group.
POST Parameters
| Parameter | Required | Value | Description |
|---|---|---|---|
api_key | {key} | An API key that has access to the resource you want to query for | |
group_id | {integer} | The group you wish to get the usage details for. If not submitted then the group of the API key will be used. |
Code Examples
The cURL, PHP, Python, Node.js, and C# examples call Xtracta from a trusted server. The React example calls an application-defined backend proxy so the API key is never exposed in browser code.
Store XTRACTA_API_KEY as a server-side environment variable. Never embed it in browser-delivered code.
curl --request POST 'https://api-app.xtracta.com/v1/billings/usage' \ --header 'Accept: application/json' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'api_key=<API_KEY>' \ --data-urlencode 'group_id=<GROUP_ID>'
Sample Request
POST https://api-app.xtracta.com/v1/billings/usage HTTP/1.1 api_key=123&group_id=456
Sample Response
<?xml version="1.0" encoding="UTF-8"?>
<billings_response>
<status>200</status>
<message>The request has been successfully processed</message>
<plan>
<id>1</id>
<plan_name>Plan A</plan_name>
<price>15</price>
<price_currency>NZD</price_currency>
<allowed_documents>250</allowed_documents>
<used_documents>0</used_documents>
<available_documents>250</available_documents>
<start_date>2015-02-27 12:10:04 (GMT)</start_date>
<expiry_date>2015-03-27 12:10:03 (GMT)</expiry_date>
<group_id>481</group_id>
</plan>
</billings_response>
Schema Definition
Response Elements
| Element | Description |
|---|---|
<status> | A status code in response to the operation |
<message> | Additional information about the operation – human readable |
<plan> | Container for current billing plan information |
<plan>→<id> | The unique ID of the billing plan |
<plan>→<plan_name> | The name of the billing plan |
<plan>→<price> | The price of the plan |
<plan>→<price_currency> | The currency code for the price (e.g., USD, NZD) |
<plan>→<allowed_documents> | The total number of documents allowed in this plan |
<plan>→<used_documents> | The number of documents already processed |
<plan>→<available_documents> | The number of documents remaining in the plan |
<plan>→<start_date> | The date when the plan started |
<plan>→<expiry_date> | The date when the plan expires |
<plan>→<group_id> | The ID of the group this plan is associated with |
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:complexType name="DowngradeType">
<xs:sequence>
<xs:element name="id" type="xs:positiveInteger"/>
<xs:element name="plan_name" type="xs:string"/>
<xs:element name="plan_type" type="xs:string"/>
<xs:element name="price" type="xs:decimal"/>
<xs:element name="price_currency" type="xs:string"/>
<xs:element name="allowed_documents" type="xs:nonNegativeInteger"/>
<xs:element name="start_date" type="xs:string"/>
<xs:element name="expiry_date" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="PlanType">
<xs:sequence>
<xs:element name="id" type="xs:positiveInteger"/>
<xs:element name="plan_name" type="xs:string"/>
<xs:element name="price" type="xs:decimal"/>
<xs:element name="price_currency" type="xs:string"/>
<xs:element name="allowed_documents" type="xs:nonNegativeInteger"/>
<xs:element name="used_documents" type="xs:nonNegativeInteger"/>
<xs:element name="available_documents" type="xs:integer"/>
<xs:element name="start_date" type="xs:string"/>
<xs:element name="expiry_date" type="xs:string"/>
<xs:element name="group_id" type="xs:positiveInteger"/>
<xs:element name="downgrade" type="DowngradeType" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="PackType">
<xs:sequence>
<xs:element name="id" type="xs:positiveInteger"/>
<xs:element name="pack_name" type="xs:string"/>
<xs:element name="price" type="xs:decimal"/>
<xs:element name="price_currency" type="xs:string"/>
<xs:element name="allowed_documents" type="xs:nonNegativeInteger"/>
<xs:element name="used_documents" type="xs:nonNegativeInteger"/>
<xs:element name="available_documents" type="xs:integer"/>
<xs:element name="start_date" type="xs:string"/>
<xs:element name="expiry_date" type="xs:string"/>
<xs:element name="group_id" type="xs:positiveInteger"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="PackSummaryType">
<xs:sequence>
<xs:element name="total_used_documents" type="xs:nonNegativeInteger"/>
<xs:element name="total_available_documents" type="xs:integer"/>
</xs:sequence>
</xs:complexType>
<xs:element name="billings_response">
<xs:complexType>
<xs:sequence>
<xs:element name="status" type="xs:positiveInteger"/>
<xs:element name="message" type="xs:string"/>
<xs:element name="plan" type="PlanType" minOccurs="0"/>
<xs:element name="pack" type="PackType" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="pack_summary" type="PackSummaryType" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="pending_documents" type="xs:positiveInteger" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Error Responses
For JSON and XML responses generated by this endpoint, the response is wrapped in billings_response and includes the HTTP status code and a message.
| Status | Message | Description |
|---|---|---|
400 | group_id must be natural number | Use a positive integer group ID. |
400 | timezone must be one of the values of [...] | Use a supported IANA timezone identifier. |
404 | No Billing Plan or Booster Pack found for the group | The group has no accessible active plan or booster pack. |
500 | Internal server error occurred. Please try again later or contact support@xtracta.com | Retry and contact support with the request parameters and timestamp if it persists. |
Authentication, permission, IP-access-control, and rate-limit failures can be returned before this endpoint processes the request. Confirm the API key and caller access first.