Returns the calling team's search sessions, oldest-first by default. Use this endpoint to discover which sessions a team has created via Property Search, audit totalDelivered counts, or identify stale sessions that should be deleted to free up one of the team's 100 session slots.
Endpoint
URL: GET /api/v2/property/search-sessions
Authentication: Bearer token (API key) — the token must have the property-search-sessions ability.
Request Structure
There is no request body. The endpoint takes two optional query string parameters for paging through a team's sessions:
Parameter | Type | Default | Description |
| integer (minimum 0) | 0 | Number of session records to skip. Used for paging. |
| integer (minimum 1, maximum 100) | 50 | Number of session records to return on this page. |
Example request:
GET /api/v2/property/search-sessions?skip=0&take=50
Authorization: Bearer YOUR_API_TOKEN
Response
{
"status": {
"code": 200,
"text": "OK"
},
"results": {
"sessions": [
{
"id": "monthly-leads-az-85020",
"totalDelivered": 5000,
"lastRequestAt": "2026-05-10T14:23:11Z",
"createdAt": "2026-04-01T09:15:00Z"
},
{
"id": "daily-crm-delta",
"totalDelivered": 12450,
"lastRequestAt": "2026-05-12T01:00:00Z",
"createdAt": "2026-03-15T08:00:00Z"
}
],
"total": 2,
"meta": {
"requestId": "01KRCV36NPGHBE6FQER77S0XZR"
}
}
}
Response Fields
results.sessions(array) — sessions belonging to the calling team. Empty array if the team has no sessions.id(string, regex^[a-zA-Z0-9_-]{1,128}$) — customer-chosen session id, scoped to the calling team.totalDelivered(integer, minimum 0) — cumulative count of unique properties delivered to this session across all requests.lastRequestAt(ISO-8601 date-time, optional) — most recent request that advanced this session. Absent if the session was created but no successful page has been delivered yet.createdAt(ISO-8601 date-time) — when the session was first created.results.total(integer) — total session count for the calling team across all pages. Use withskip/taketo drive a paginator.results.meta.requestId(string) — unique identifier for this request. Surface in support contacts for tracing.
This response's meta block carries only requestId — no nested meta.results block — because no Elasticsearch query was run.
curl example
curl -X GET 'https://api.batchdata.com/api/v2/property/search-sessions?skip=0&take=50' \
-H 'Authorization: Bearer YOUR_API_TOKEN'
Cross-tenant isolation
Sessions are scoped strictly to the calling team. Sessions belonging to another team are never returned, listed, or acknowledged — even if their id matches one your team has used. This is the same isolation guarantee that backs DELETE /api/v2/property/search-sessions/{id}'s 404 behavior.
Error responses
Status | Body message | Cause |
401 | (standard auth error) | Missing or invalid Bearer token. |
403 |
| Token is missing the |
429 | (standard rate-limit error) | Exceeded 3,000 requests per minute for the calling token. |
Anti-patterns to avoid
Polling this endpoint to detect new session activity. It's a list endpoint, not a change feed. If you need to know whether a session has advanced, the
searchSessionMeta.totalDeliveredfield on each Property Search response tells you precisely.Calling without the
property-search-sessionsability and treating the 403 as a bug. The 403 is intentional. Update the token in Token Management.Using
taketo mean "max sessions allowed."takeis a paging parameter; the per-team cap of 100 sessions is enforced server-side regardless oftake.
Related articles
BatchData Property Search Request Body Reference — how to create a session via
options.searchSession.Delete Search Session (
DELETE /api/v2/property/search-sessions/{searchSessionId}) — free up a session slot when one is no longer needed.Incremental Property Search: Cursor Pagination & Search Sessions — when to use each paging mode, with worked examples.