Skip to main content
500CallsDocs
Browse the docs

List messages

GET/v1/messages

Lists messages newest first. Filters combine; status and source repeat. With neither time bound the last 7 days are listed, and one request spans at most the report range (92 days by default). Pass next_cursor back as cursor for the next page.

Scope
messages:read

Request

Every request needs an API key in the Authorization header, and the key needs the scope the endpoint names.

Parameters

  • statusqueryarray of string

    Only messages with this status. Repeat it for several; queued also matches messages being sent.

    • One of: scheduled, queued, sent, delivered, undelivered, expired, rejected, failed, cancelled
  • fromquerystring

    Only messages from this sender ID (not case-sensitive).

    • At most 64 characters
  • toquerystring

    Only messages to this recipient, in any format a send accepts.

    • At most 256 characters
  • client_referencequerystring

    Only messages with exactly this reference.

    • At most 64 characters
  • campaign_idquerystring

    Only messages of this campaign, cmp_….

    • Matches ^cmp_[0-9A-HJKMNP-TV-Z]{26}$
  • sourcequeryarray of string

    Only messages sent this way. Repeat it for several.

    • One of: api, campaign, quick_send, test_send
  • created_afterquerystring (date-time)

    Only messages created at or after this time, at most 12 months ago. With neither bound, the last 7 days are listed.

  • created_beforequerystring (date-time)

    Only messages created before this time (now by default). With only created_before, the 7 days before it are listed. One request spans at most 92 days by default.

  • limitqueryinteger

    How many items to return, from 1 to 100 (50 by default).

    • From 1 to 100
    • Defaults to 50
  • cursorquerystring

    The next_cursor of the previous page.

    • At most 256 characters
Example request
GET /v1/messages?client_reference=order-78123&limit=10

Responses

200 OK

ReturnsMessageList

  • dataarray of MessageRequired

    The messages on this page, newest first.

  • next_cursorstringor nullRequired

    Pass this back as cursor for the next page; null on the last page.

Headers

  • Cache-ControlstringRequired

    Responses are never cached.

  • RateLimit-Limitinteger

    Requests per second your account may sustain.

  • RateLimit-Remaininginteger

    Whole requests left in your account's bucket.

  • RateLimit-Resetinteger

    Seconds until the bucket is full again.

  • X-Request-IdstringRequired

    This request's ID, also given as request_id in error bodies. Quote it to support.

Example response
{  "data": [    {      "id": "msg_01M3KR6CEGVQVV5PV6Q9J1G6SP",      "object": "message",      "amount": "3.2000",      "body": "Your ACME code is 482913. It expires in 5 minutes.",      "campaign_id": null,      "channel": "sms",      "client_reference": "order-78123",      "completed_at": "2026-09-28T10:15:39.870Z",      "created_at": "2026-09-28T10:15:30.000Z",      "currency": "NGN",      "direction": "outbound",      "encoding": "gsm7",      "error": null,      "from": "ACME",      "held_amount": "3.5000",      "mode": "live",      "scheduled_at": null,      "segments": 1,      "sent_at": "2026-09-28T10:15:31.412Z",      "source": "api",      "status": "delivered",      "to": "+2348031234567",      "unit_price": "3.2000",      "updated_at": "2026-09-28T10:15:39.870Z"    }  ],  "next_cursor": null}

Errors

Each code links to its page. Branch on the code, never on the title or detail.

Example 422 response
{  "type": "https://docs.messaging.500calls.com/errors/validation_error",  "title": "Validation error",  "status": 422,  "code": "validation_error",  "detail": "1 parameter failed validation.",  "request_id": "req_01M3KR6CQ26S90NG2V790GVFTX",  "errors": [    {      "field": "created_before",      "code": "range_too_large",      "message": "created_before can be at most 92 days after created_after (created_before defaults to now)."    }  ]}

Code samples

Each sample reads your key from the API_KEY_500CALLS environment variable.

cURL
curl 'https://api.messaging.500calls.com/v1/messages?client_reference=order-78123&limit=10' \  -H "Authorization: Bearer $API_KEY_500CALLS"
Python
import osimport requestsresponse = requests.get(    "https://api.messaging.500calls.com/v1/messages?client_reference=order-78123&limit=10",    headers={        "Authorization": f"Bearer {os.environ['API_KEY_500CALLS']}",    },    timeout=30,)print(response.status_code, response.json())
Node.js
const response = await fetch("https://api.messaging.500calls.com/v1/messages?client_reference=order-78123&limit=10", {  headers: {    Authorization: `Bearer ${process.env.API_KEY_500CALLS}`,  },});console.log(response.status, await response.json());
PHP
<?php$curl = curl_init('https://api.messaging.500calls.com/v1/messages?client_reference=order-78123&limit=10');curl_setopt_array($curl, [    CURLOPT_HTTPHEADER => [        'Authorization: Bearer ' . getenv('API_KEY_500CALLS'),    ],    CURLOPT_RETURNTRANSFER => true,]);$body = curl_exec($curl);$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);echo $status, PHP_EOL, $body, PHP_EOL;