Deletes the named session and every byte of its delivered-id state. Frees one of the team's 100 session slots immediately. Recreating the same session id later starts a fresh session that begins from page 1.
Endpoint
URL: DELETE /api/v2/property/search-sessions/{searchSessionId}
Authentication: Bearer token (API key) — the token must have the property-search-sessions ability.
Path Parameter
searchSessionId(string, required, regex^[a-zA-Z0-9_-]{1,128}$, max length 128) — the id of the session to delete. Values with/,.., whitespace, or other special characters are rejected with 400.
Example request
DELETE /api/v2/property/search-sessions/monthly-leads-az-85020
Authorization: Bearer YOUR_API_TOKEN
Response
{
"status": {
"code": 200,
"text": "OK"
},
"results": {
"deleted": true,
"id": "monthly-leads-az-85020",
"meta": {
"requestId": "01KRCV49383QRW53VBJX6CVDCT"
}
}
}
Response Fields
results.deleted(boolean) — alwaystrueon a 2xx response. Failures route through the error branches below, not throughdeleted: false.results.id(string) — echoes the session id that was deleted.results.meta.requestId(string) — unique identifier for this request. Surface in support contacts for tracing.
curl example
curl -X DELETE 'https://api.batchdata.com/api/v2/property/search-sessions/monthly-leads-az-85020' \
-H 'Authorization: Bearer YOUR_API_TOKEN'
Cross-tenant isolation
Sessions are scoped strictly to the calling team. If the supplied searchSessionId exists for a different team, this endpoint returns 404 — the same response you'd get if the id didn't exist anywhere. Surfacing 403 in the cross-tenant case would confirm the existence of another tenant's session id and enable cross-tenant enumeration; the 404 is intentional.
Error responses
Status | Body message | Cause |
400 |
| Path parameter failed validation (regex or length). |
401 | (standard auth error) | Missing or invalid Bearer token. |
403 |
| Token is missing the |
404 |
| The session id does not exist for the calling team. Returned even if the same id exists for a different team — by design (see above). |
429 | (standard rate-limit error) | Exceeded 3,000 requests per minute for the calling token. |
Recreate behavior
Deleting a session is permanent — its delivered-id state cannot be recovered. If the same session id is later sent again in a Property Search request, a brand-new session is created with isNewSession: true and totalDelivered: 0. The new session has no memory of the previous session's deliveries, so any properties that matched the prior session will be eligible for delivery (and billing) again.
Anti-patterns to avoid
Deleting a session to "reset" it mid-job. That re-introduces the duplicate-delivery problem the session was solving. If you want to skip ahead, end the job; if you want to restart from the top, delete the session and accept that previously-delivered properties will be re-delivered.
Treating the 404 as a bug. The 404 is intentional for both "doesn't exist" and "exists for another team." If you expected the session to be there, check whether you deleted it earlier or whether you're calling with the wrong token.
Retrying on 400. If the path parameter failed validation, retrying with the same value will fail the same way. Fix the id (regex
^[a-zA-Z0-9_-]{1,128}$) and try again.
Related articles
BatchData Property Search Request Body Reference — how to create a session via
options.searchSession.List Search Sessions (
GET /api/v2/property/search-sessions) — see which sessions the calling team has, withtotalDeliveredcounts and timestamps.Incremental Property Search: Cursor Pagination & Search Sessions — when to use each paging mode, with worked examples.