curl "https://api.bota.dev/v1/end-users?limit=10" \
-H "Authorization: Bearer sk_test_..."
const response = await fetch('https://api.bota.dev/v1/end-users?limit=10', {
headers: {
'Authorization': 'Bearer sk_test_...',
},
});
const { data, has_more } = await response.json();
import requests
response = requests.get(
'https://api.bota.dev/v1/end-users',
headers={'Authorization': 'Bearer sk_test_...'},
params={'limit': 10},
)
result = response.json()
end_users = result['data']
{
"data": [
{
"id": "eu_abc123",
"external_id": "user_12345",
"email": "john@example.com",
"name": "John Doe",
"metadata": {
"plan": "pro"
},
"created_at": "2025-01-15T10:30:00Z"
},
{
"id": "eu_def456",
"external_id": "user_67890",
"email": "jane@example.com",
"name": "Jane Smith",
"metadata": null,
"created_at": "2025-01-14T09:00:00Z"
}
],
"has_more": true,
"next_cursor": "eyJpZCI6ImV1X2RlZjQ1NiIsInRzIjoiMjAyNS0wMS0xNFQwOTowMDowMC4wMDBaIn0"
}
End Users
List End Users
Retrieve or look up end users in your project
GET
/
end-users
curl "https://api.bota.dev/v1/end-users?limit=10" \
-H "Authorization: Bearer sk_test_..."
const response = await fetch('https://api.bota.dev/v1/end-users?limit=10', {
headers: {
'Authorization': 'Bearer sk_test_...',
},
});
const { data, has_more } = await response.json();
import requests
response = requests.get(
'https://api.bota.dev/v1/end-users',
headers={'Authorization': 'Bearer sk_test_...'},
params={'limit': 10},
)
result = response.json()
end_users = result['data']
{
"data": [
{
"id": "eu_abc123",
"external_id": "user_12345",
"email": "john@example.com",
"name": "John Doe",
"metadata": {
"plan": "pro"
},
"created_at": "2025-01-15T10:30:00Z"
},
{
"id": "eu_def456",
"external_id": "user_67890",
"email": "jane@example.com",
"name": "Jane Smith",
"metadata": null,
"created_at": "2025-01-14T09:00:00Z"
}
],
"has_more": true,
"next_cursor": "eyJpZCI6ImV1X2RlZjQ1NiIsInRzIjoiMjAyNS0wMS0xNFQwOTowMDowMC4wMDBaIn0"
}
Retrieve a paginated list of end users in your project. To look up the end user
associated with an identifier from your system, filter the collection by
An exact match returns the end user in the standard collection response:
When no active end user in the project matches,
Each end user object in
external_id.
Authentication
Requires an API key withend_users:read scope.
curl "https://api.bota.dev/v1/end-users?limit=10" \
-H "Authorization: Bearer sk_test_..."
const response = await fetch('https://api.bota.dev/v1/end-users?limit=10', {
headers: {
'Authorization': 'Bearer sk_test_...',
},
});
const { data, has_more } = await response.json();
import requests
response = requests.get(
'https://api.bota.dev/v1/end-users',
headers={'Authorization': 'Bearer sk_test_...'},
params={'limit': 10},
)
result = response.json()
end_users = result['data']
Query Parameters
integer
default:"20"
Maximum number of items to return (1-100).
string
Cursor returned by the previous page. See Pagination.
string
Return the active end user whose
external_id exactly matches this value.
The lookup is scoped to the authenticated project and returns at most one item.Look up by external ID
cURL
curl --get "https://api.bota.dev/v1/end-users" \
-H "Authorization: Bearer sk_test_..." \
--data-urlencode "external_id=user_12345"
200
{
"data": [
{
"id": "eu_abc123",
"external_id": "user_12345",
"email": "john@example.com",
"name": "John Doe",
"metadata": {
"plan": "pro"
},
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
],
"has_more": false
}
data is empty:
200
{
"data": [],
"has_more": false
}
The lookup never reveals whether the same
external_id exists in another
project. A missing, deleted, or inaccessible end user produces the same empty
result.Response
Returns a paginated list of end user objects.{
"data": [
{
"id": "eu_abc123",
"external_id": "user_12345",
"email": "john@example.com",
"name": "John Doe",
"metadata": {
"plan": "pro"
},
"created_at": "2025-01-15T10:30:00Z"
},
{
"id": "eu_def456",
"external_id": "user_67890",
"email": "jane@example.com",
"name": "Jane Smith",
"metadata": null,
"created_at": "2025-01-14T09:00:00Z"
}
],
"has_more": true,
"next_cursor": "eyJpZCI6ImV1X2RlZjQ1NiIsInRzIjoiMjAyNS0wMS0xNFQwOTowMDowMC4wMDBaIn0"
}
Response Fields
| Field | Type | Description |
|---|---|---|
data | array | Array of end user objects. |
has_more | boolean | Whether there are more results beyond this page. |
next_cursor | string | Opaque cursor for the next page. Present only when has_more is true. |
data contains:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the end user (prefixed with eu_). |
external_id | string | Your system’s unique identifier for this user. |
email | string | User’s email address. |
name | string | User’s display name. |
metadata | object | Arbitrary key-value metadata. |
created_at | string | ISO 8601 timestamp of when the end user was created. |
Was this page helpful?