---
title: "Queue an async mass unlock task for raw search"
method: POST
path: "/search/raw/unlock/task"
tags: ["Raw Search"]
---

# Queue an async mass unlock task for raw search

`POST /search/raw/unlock/task`

Creates an asynchronous unlock **Task** for the given raw search filters. Returns a `task_id` you can poll with the task-status endpoint.

**Request body**
- `q`: Optional search string (minimum 4 characters if provided). Required if no other filter is provided.
- `container_id`: Optional container identifier.
- `exts`: Optional list of file extensions to keep.
- `exts_not`: Optional list of file extensions to exclude.
- `categories`: Optional list of raw file categories.
- `categories_not`: Optional list of raw file categories to exclude.
- `file_name`: Optional match on `entry_name`.
- `file_name_not`: Optional match that must NOT hold on `entry_name`.
- `file_name_match_type` / `file_name_not_match_type`: `contains` (default), `starts_with`, `ends_with` or `exact`, one per list.
- `folder_name`: Optional match on the folder holding the block (max 20 items, min 4 chars each).
- `folder_name_not`: Optional folders to exclude. Not a standalone selector.
- `folder_name_match_type` / `folder_name_not_match_type`: `contains` (default), `starts_with`, `ends_with` or `exact` (a whole folder at any depth), one per list.
- `file_name_exact` / `folder_name_exact`: Deprecated, `true` means `exact` on both lists when no match type is given.
- `exclude_terms`: Optional content terms to exclude (substring, case-insensitive, max 20, min 4 chars each).
- `ingested_at_min`: Optional datetime to filter results ingested on or after.
- `ingested_at_max`: Optional datetime to filter results ingested on or before.

**Query parameters**
- `max`: Optional cap of new unlocks. 0 or omitted = use all your points.

**Plan requirement**
Requires a paid plan with `raw_search` enabled.

**Concurrency limit**
- raw: max 1 running and 1 queued task per account.
- identical active requests return the existing task id.
- email / domain: max 5 concurrent tasks per user.
- Returns 429 if limit exceeded.

## Query parameters

- `max` integer, nullable — 0 or omitted = use all your points
- `dedup` boolean — Skip blocks with identical content (same block_fp64) so each unique content is unlocked once. Matches the deduplicated search/export view.

## Request body

- RawSearchRequest
  - `q` string, nullable — Optional full text query to match within raw blocks. Quotes are ignored for the length check. When omitted or empty, you must provide at least one filter among container_id, exts, categories, file_name.
  - `container_id` integer, nullable — Restrict the search to a specific container id.
  - `exts` string[], nullable — List of file extensions to include (case-insensitive, without leading dot).
  - `exts_not` string[], nullable — List of file extensions to exclude (case-insensitive, without leading dot).
  - `categories` string[], nullable — Filter results by raw file category. Applied after the search query.
  - `categories_not` string[], nullable — Exclude these raw file categories. Applied after the search query.
  - `file_name` string[], nullable — Case-insensitive wildcards that must match the entry name (OR by default, AND if force_and=true).
  - `file_name_not` string[], nullable — Case-insensitive wildcards that must NOT match the entry name.
  - `folder_name` string[], nullable — Case-insensitive match on the folder holding the block (OR by default, AND if force_and=true). By default the value must appear anywhere in the folder path; with folder_name_exact=true it must be a whole folder at any depth. Leading and trailing slashes are ignored.
  - `folder_name_not` string[], nullable — Folders to exclude, same matching rules as folder_name. Not a standalone selector: a search using only folder_name_not is rejected, provide q or another positive filter.
  - `force_and` boolean, nullable — When true, require all file_name values to match, and all folder_name values to match (AND instead of OR within each list).
  - `file_name_match_type` 'contains' | 'starts_with' | 'ends_with' | 'exact' — How a raw file-name or folder value is matched. Separate from AdvancedTextMatchType on purpose: raw has an EXACT mode the stealer fields do not, and adding it there would widen a contract that seven surfaces already depend on.
  - `file_name_not_match_type` 'contains' | 'starts_with' | 'ends_with' | 'exact' — How a raw file-name or folder value is matched. Separate from AdvancedTextMatchType on purpose: raw has an EXACT mode the stealer fields do not, and adding it there would widen a contract that seven surfaces already depend on.
  - `folder_name_match_type` 'contains' | 'starts_with' | 'ends_with' | 'exact' — How a raw file-name or folder value is matched. Separate from AdvancedTextMatchType on purpose: raw has an EXACT mode the stealer fields do not, and adding it there would widen a contract that seven surfaces already depend on.
  - `folder_name_not_match_type` 'contains' | 'starts_with' | 'ends_with' | 'exact' — How a raw file-name or folder value is matched. Separate from AdvancedTextMatchType on purpose: raw has an EXACT mode the stealer fields do not, and adding it there would widen a contract that seven surfaces already depend on.
  - `file_name_exact` boolean, nullable — Deprecated, use file_name_match_type and file_name_not_match_type. When true and neither is given, both file_name and file_name_not are matched as `exact`.
  - `folder_name_exact` boolean, nullable — Deprecated, use folder_name_match_type and folder_name_not_match_type. When true and neither is given, both folder_name and folder_name_not are matched as `exact`.
  - `q_exact` boolean, nullable — When true, the q term must match on word boundaries: '4.4.4.4' will not match '4.4.4.400'. Applied as a content post-filter (no effect without q).
  - `exclude_terms` string[], nullable — Content terms to exclude: any block whose content contains one of these (substring, case-insensitive) is removed from the results. Min 4 characters per term, max 20 terms. Not a standalone selector: a search using only exclude_terms is rejected, provide q or another positive filter.
  - `ingested_at_min` string, date-time, nullable — Filter results ingested on or after this datetime (inclusive).
  - `ingested_at_max` string, date-time, nullable — Filter results ingested on or before this datetime (inclusive).

## Response `200`

Unlock task queued; returns a task_id to poll.

- object

## Other responses

- `400` — Invalid query (too short, too long, or empty with no filters), insufficient points, unlock not needed on your plan.
- `401` — Authentication required, or invalid/expired API key.
- `403` — Raw search not available on your plan, this search is blocked, account banned, or pending email verification.
- `422` — Validation Error
- `429` — Rate limit exceeded, or the account already has a queued raw unlock task.
- `503` — Raw search under maintenance, or public API temporarily disabled.

## Changes

- **2026-09-04** `eb219e94d077` — 4 info
  - added the new optional request property `file_name_match_type`
  - added the new optional request property `file_name_not_match_type`
  - added the new optional request property `folder_name_match_type`
  - added the new optional request property `folder_name_not_match_type`

[Change history](https://skmtc.dev/leakradar/apis/leakradar-io-api/changes/search/raw/unlock/task/post.md)

---

[API](https://skmtc.dev/leakradar/apis/leakradar-io-api.md) · [All operations](https://skmtc.dev/leakradar/apis/leakradar-io-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/leakradar/leakradar-io-api/revisions/eb219e94d077/schema)