Account & Stats — SimCoal — SMS API

GET

/account

Returns full account information including plan type, credit balance, and monthly quota details.

Endpoint

GET  https://coals.ai/api/v1/simcoal/account

Response — 200 OK

{
  "success": true,
  "team_name": "Acme Corp",
  "plan_type": "pro",
  "balance": 12.50,
  "quota_monthly": 5000,
  "quota_used": 1243,
  "quota_remaining": 3757,
  "quota_reset_date": "2026-04-01"
}

Field	Description
team_name	Display name of the authenticated team.
plan_type	Active plan: `free`, `starter`, `pro`, or `enterprise`.
balance	Current credit balance in USD.
quota_monthly	Total SMS messages allowed per billing cycle.
quota_used	Messages sent in the current billing cycle.
quota_remaining	Messages remaining before quota is exhausted.
quota_reset_date	Date the quota resets in `YYYY-MM-DD` format.

curl Example

curl https://coals.ai/api/v1/simcoal/account \
  -H "Authorization: Bearer YOUR_API_KEY"

// Using Guzzle
$response = $client->get('https://coals.ai/api/v1/simcoal/account', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.get(
  "https://coals.ai/api/v1/simcoal/account",
  headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

# Using net/http
require "net/http"
require "json"

uri = URI("https://coals.ai/api/v1/simcoal/account")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

// Using fetch (Node 18+)
const response = await fetch("https://coals.ai/api/v1/simcoal/account", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});
const data = await response.json();

GET

/account/balance

Lightweight endpoint that returns only the current credit balance. Useful for balance checks before initiating large sends.

Endpoint

GET  https://coals.ai/api/v1/simcoal/account/balance

Response — 200 OK

{
  "success": true,
  "balance": 12.50
}

curl Example

curl https://coals.ai/api/v1/simcoal/account/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

// Using Guzzle
$response = $client->get('https://coals.ai/api/v1/simcoal/account/balance', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.get(
  "https://coals.ai/api/v1/simcoal/account/balance",
  headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

# Using net/http
require "net/http"
require "json"

uri = URI("https://coals.ai/api/v1/simcoal/account/balance")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

// Using fetch (Node 18+)
const response = await fetch("https://coals.ai/api/v1/simcoal/account/balance", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});
const data = await response.json();

GET

/stats

Returns aggregated messaging statistics for your team: send totals, delivery success rate, and cost breakdown.

Endpoint

GET  https://coals.ai/api/v1/simcoal/stats

Response — 200 OK

{
  "success": true,
  "total_sent": 4821,
  "sent_today": 37,
  "sent_this_month": 1243,
  "success_rate": 98.4,
  "total_cost": 36.16
}

Field	Description
total_sent	All-time message count for this team.
sent_today	Messages sent since midnight UTC today.
sent_this_month	Messages sent in the current billing cycle.
success_rate	Percentage of messages with `delivered` or `sent` status, as a float (e.g. `98.4` means 98.4%).
total_cost	Total credits spent on messages, in USD.

curl Example

curl https://coals.ai/api/v1/simcoal/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

// Using Guzzle
$response = $client->get('https://coals.ai/api/v1/simcoal/stats', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.get(
  "https://coals.ai/api/v1/simcoal/stats",
  headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

# Using net/http
require "net/http"
require "json"

uri = URI("https://coals.ai/api/v1/simcoal/stats")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

// Using fetch (Node 18+)
const response = await fetch("https://coals.ai/api/v1/simcoal/stats", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});
const data = await response.json();