Lookups
List phone-number lookups
List the phone-number lookups your organization has run, newest first.
Results are cursor paginated. The next-page token is returned in
meta.next_cursor, which is null on the last page.
Lookup results are retained for 90 days. After that, a lookup still
appears in the list but its result is null and result_redacted_at
is populated.
Requires the lookups:read scope.
AuthorizationBearer <token>
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Query Parameters
cursor?string
limit?integer
Default
50Range
1 <= value <= 200phone_number?string
status?string
Value in
"pending" | "processing" | "complete" | "failed"since?string
Format
date-timeuntil?string
Format
date-timeResponse Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/lookup"{
"success": true,
"data": [
{
"id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
"phone_number": "+15551234567",
"lookup_type": "advanced",
"status": "complete",
"result": {
"line_type": "MOBILE",
"messaging_provider": "T-Mobile USA, Inc.",
"voice_provider": "T-Mobile USA, Inc.",
"country_code": "USA"
},
"result_redacted_at": null,
"error_code": null,
"error_message": null,
"requested_at": "2026-04-30T15:23:01Z",
"completed_at": "2026-04-30T15:23:01.847Z",
"cost_cents": 2
},
{
"id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b6",
"phone_number": "+15558675309",
"lookup_type": "advanced",
"status": "complete",
"result": null,
"result_redacted_at": "2026-01-29T03:11:42Z",
"error_code": null,
"error_message": null,
"requested_at": "2025-10-30T15:23:01Z",
"completed_at": "2025-10-30T15:23:02.014Z",
"cost_cents": 2
}
],
"meta": {
"total": 0,
"limit": 50,
"offset": 0,
"next_cursor": null
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}