Logs — SimCoal — SMS API

GET

/logs

Retrieve a paginated list of outbound SMS message logs for your team. Supports filtering by status, phone number, and date range. Requires the simcoal:read scope.

Endpoints

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

GET  https://coals.ai/api/v1/simcoal/logs/{id}

Query Parameters — `GET /logs`

Parameter	Type	Required	Description
status	string	optional	Filter by delivery status. Accepted values: `sent`, `delivered`, `failed`.
phone_number	string	optional	Partial phone number match. Searches the `to` field with a prefix match (e.g. `555` matches all 555-xxx numbers).
date_from	string	optional	Start of date range in `YYYY-MM-DD` format. Inclusive.
date_to	string	optional	End of date range in `YYYY-MM-DD` format. Inclusive.
per_page	integer	optional	Results per page. Default `25`, maximum `100`.
page	integer	optional	Page number to retrieve. Default `1`.

Response — GET /logs (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "msg_001",
      "to": "5551234567",
      "carrier": "verizon",
      "message": "Hello from SimCoal!",
      "status": "delivered",
      "cost": 0.0075,
      "provider": "email_sms",
      "sent_at": "2026-03-03T14:22:00Z"
    }
  ],
  "pagination": {
    "total": 142,
    "per_page": 25,
    "current_page": 1,
    "last_page": 6
  }
}

Response — GET /logs/{id} (200 OK)

Returns a single log entry. Useful for polling delivery status after a send.

{
  "success": true,
  "data": {
    "id": "msg_001",
    "to": "5551234567",
    "carrier": "verizon",
    "message": "Hello from SimCoal!",
    "status": "delivered",
    "cost": 0.0075,
    "provider": "email_sms",
    "sent_at": "2026-03-03T14:22:00Z",
    "delivered_at": "2026-03-03T14:22:04Z"
  }
}

curl Examples

List failed messages from the last 7 days:

curl -G https://coals.ai/api/v1/simcoal/logs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "status=failed" \
  --data-urlencode "date_from=2026-02-24" \
  --data-urlencode "date_to=2026-03-03"

// Using Guzzle
$response = $client->get('https://coals.ai/api/v1/simcoal/logs', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
  'query' => [
    'status' => 'failed',
    'date_from' => '2026-02-24',
    'date_to' => '2026-03-03',
  ]
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.get(
  "https://coals.ai/api/v1/simcoal/logs",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  params={"status": "failed", "date_from": "2026-02-24", "date_to": "2026-03-03"}
)
data = response.json()

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

uri = URI("https://coals.ai/api/v1/simcoal/logs")
uri.query = URI.encode_www_form({"status" => "failed", "date_from" => "2026-02-24", "date_to" => "2026-03-03"})
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/logs?status=failed&date_from=2026-02-24&date_to=2026-03-03`, {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});
const data = await response.json();

Retrieve a single log entry by ID:

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

// Using Guzzle
$response = $client->get('https://coals.ai/api/v1/simcoal/logs/msg_001', [
  '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/logs/msg_001",
  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/logs/msg_001")
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/logs/msg_001", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});
const data = await response.json();

Log entries are retained for 90 days. Logs older than 90 days are automatically purged. Export important records before they expire.