Get Usage

Retrieve how much of your plan your organization has used in the current period.

The period is the UTC calendar month

Usage is counted per UTC calendar month, from period_start up to but not including period_end. This is not your billing cycle: counters reset on the first of each month regardless of when you subscribed.

Endpoint

GET /usage

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	Yes

Response

{
  "object": "usage",
  "period_start": "2026-03-01T00:00:00.000Z",
  "period_end": "2026-04-01T00:00:00.000Z",
  "emails": {
    "marketing": { "used": 18240, "limit": 50000, "remaining": 31760 },
    "transactional": { "used": 912, "limit": 10000, "remaining": 9088 }
  },
  "sms": { "used": 4310, "limit": null, "remaining": null },
  "whatsapp": { "used": 126, "limit": 1000, "remaining": 874 },
  "push": { "used": 73400, "limit": null, "remaining": null },
  "in_app": { "used": 0, "limit": 100000, "remaining": 100000 },
  "automation_runs": { "used": 388, "limit": 1000, "remaining": 612 },
  "contacts": { "used": 41250, "limit": 50000, "remaining": 8750 }
}

Response fields

Field	Type	Description
period_start	string	Start of the current period (ISO 8601)
period_end	string	Exclusive end of the period: the instant the next one starts
emails.marketing	meter	Marketing emails: campaigns and automations
emails.transactional	meter	Transactional emails, sent through POST /email/send or SMTP
sms	meter	SMS credits. One credit is one message part, so a long or non-Latin message uses several.
whatsapp	meter	WhatsApp messages
push	meter	Push notifications
in_app	meter	In-app messages
automation_runs	meter	Automation runs
contacts	meter	Contacts in the organization right now, against the plan limit. Not a per-period counter.

Every meter has the same three fields:

Field	Type	Description
used	number	The amount used so far
limit	number | null	The plan's limit. null means the plan sets no limit.
remaining	number | null	What is left of limit, never below 0. null when there is no limit.

Balances and prices are not part of this response.

---

Examples

cURL

curl "https://api.arsel.sa/v1/usage" \
  -H "Authorization: Bearer be_your_api_key"

JavaScript

const response = await fetch(
  "https://api.arsel.sa/v1/usage",
  {
    headers: { Authorization: "Bearer be_your_api_key" },
  }
);

const usage = await response.json();
const { used, limit, remaining } = usage.emails.marketing;
console.log(limit === null ? `${used} sent, no limit` : `${remaining} of ${limit} left`);

Python

import requests

response = requests.get(
    "https://api.arsel.sa/v1/usage",
    headers={"Authorization": "Bearer be_your_api_key"},
)

usage = response.json()
meter = usage["emails"]["marketing"]
if meter["limit"] is None:
    print(meter["used"], "sent, no limit")
else:
    print(meter["remaining"], "of", meter["limit"], "left")

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer be_your_api_key");

var response = await client.GetAsync("https://api.arsel.sa/v1/usage");
Console.WriteLine(await response.Content.ReadAsStringAsync());

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/usage");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
echo $response;
curl_close($ch);

---

Error Responses

401 Unauthorized

{
  "status_code": 401,
  "name": "unauthorized",
  "message": "Invalid or missing API key"
}