Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

Retrieve up to 80,000 player records (Subscriptions) registered to a specific OneSignal app.
This is a Legacy API. Use View User or CSV Export API instead.

​
Query Parameters

ParameterTypeRequiredDescription
app_idstringYesYour OneSignal App ID.
limitintNoNumber of entries to return (max 300, default is 300).
offsetintNoResult offset for pagination.

​
Headers

HeaderValueRequiredDescription
AuthorizationBasic YOUR_LEGACY_REST_API_KEYYesYour OneSignal Legacy REST API Key.

​
Example Request

GET /api/v1/players?app_id=your_app_id&limit=100&offset=0 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY

​
Example Response

{
  "total_count": 6,
  "offset": 0,
  "limit": 300,
  "players": [
    {
      "id": "player_id_1",
      "identifier": "push_token_or_email",
      "session_count": 3,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "15.0",
      "device_type": 1,
      "tags": {
        "level": "15",
        "user_type": "free"
      },
      "last_active": 1625253300,
      "created_at": 1625249800,
      "invalid_identifier": false,
      "external_user_id": "user123"
    }
  ]
}

​
Response Fields

FieldTypeDescription
total_countintegerTotal number of devices for the app.
offsetintegerCurrent pagination offset.
limitintegerNumber of devices returned in this response.
playersarrayList of device objects.
players[].idstringUnique OneSignal player ID.
players[].identifierstringPush token, email, or phone number.
players[].tagsobjectCustom tags set on the device.
players[].external_user_idstringYour internal user ID.

​
Errors

  • 400 Bad Request – Invalid query parameters.
  • 401 Unauthorized – Invalid or missing API key.
  • 403 Forbidden – Access not allowed for this app or key.