> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parsagon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create advanced search

> Create a persistent Search object processed asynchronously, with results and an AI-generated report available via polling.

The Advanced Search endpoint creates a persistent Search object. The server processes the search asynchronously. Use the returned `id` to poll for completion.

Unlike Quick Search, Advanced Search supports date ranges up to 90 days and produces an AI-generated report alongside raw results.

## Request body

<ParamField body="categories" type="array" required>
  Array of category IDs to include in the search results.
</ParamField>

<ParamField body="context" type="string">
  Additional context for the AI to tailor the search and reporting (for example, your organization or focus area). Maximum 1000 characters.
</ParamField>

<ParamField body="filter_prompt" type="string" required>
  A list of policy topics to search for, one per line. Longer, descriptive phrases work best. Maximum 5000 characters.
</ParamField>

<ParamField body="edit_prompt" type="string">
  Optional instructions for formatting or transforming the search results into `edited_results`. Omit this field if you only need raw `search_results`. Maximum 5000 characters.
</ParamField>

<ParamField body="labels" type="object">
  A dictionary of string key-value pairs for your own record keeping. Use this to attach metadata to the search, such as the project or team it belongs to (for example, `{"project": "tax-reform", "team": "policy"}`).
</ParamField>

<ParamField body="is_test" type="boolean">
  Set to `true` to validate the request and create a Search with example data without running a source search. Required fields such as `categories`, `filter_prompt`, and `date_range` are still validated normally.
</ParamField>

<ParamField body="test_data" type="object">
  Custom dummy data to store when `is_test` is `true`. Use this to test downstream handling of `search_results` or custom `edited_results` formats.

  <Expandable title="Test data fields">
    <ParamField body="search_results" type="array">
      Array of search result objects to store instead of Parsagon's built-in example results.
    </ParamField>

    <ParamField body="edited_results" type="any">
      Custom edited output to store as `edited_results`. This value is not generated from `edit_prompt`; it is stored exactly as provided.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="date_range" type="object" required>
  Time period to search within. May cover up to **90 days** — use either `start_date`/`end_date` or `duration_seconds` ≤ 7776000.

  <Expandable title="Fixed range">
    <ParamField body="start_date" type="string">
      ISO 8601 datetime (UTC). The earliest supported value is 90 days before the time of the request.
    </ParamField>

    <ParamField body="end_date" type="string">
      ISO 8601 datetime (UTC).
    </ParamField>
  </Expandable>

  <Expandable title="Relative duration">
    <ParamField body="duration_seconds" type="number">
      Positive number of seconds before "now" to search within (maximum 7776000).
    </ParamField>
  </Expandable>
</ParamField>

## Response

On success, returns the created Search object. The create response does not include `search_results` or `edited_results`. Use the returned `id` to [retrieve the Search](/api-reference/endpoint/get-search) and read results.

<ResponseField name="id" type="number | string">
  Unique identifier for the Search. Use this to [retrieve results](/api-reference/endpoint/get-search).
</ResponseField>

<ResponseField name="categories" type="array">
  Array of category IDs used in the search.
</ResponseField>

<ResponseField name="context" type="string">
  Context provided in the request.
</ResponseField>

<ResponseField name="filter_prompt" type="string">
  Filter prompt provided in the request.
</ResponseField>

<ResponseField name="edit_prompt" type="string">
  Edit prompt provided in the request.
</ResponseField>

<ResponseField name="labels" type="object">
  Labels provided in the request.
</ResponseField>

<ResponseField name="is_test" type="boolean">
  Whether the Search was created in test mode.
</ResponseField>

<ResponseField name="date_range" type="object">
  The date range used, containing either `start_date` and `end_date`, or `duration_seconds`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the Search was created (ISO 8601, UTC).
</ResponseField>

<ResponseField name="n_potential" type="number">
  Estimated number of candidate results to process.
</ResponseField>

<ResponseField name="n_processed" type="number">
  Number of candidate results processed so far.
</ResponseField>

<ResponseField name="returned_up_to_idx" type="number">
  Internal pagination position for additional result pages.
</ResponseField>

<ResponseField name="uuid" type="string">
  Public UUID for the Search.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if an error occurred; otherwise `null`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://parsagon.io/api/events/v1/search/" \
    -H "Authorization: Token YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "categories": [74],
      "context": "User needs to keep track of financial services regulations in the UK",
      "filter_prompt": "Policies related to financial market stability and supervision of financial institutions\nConsumer protection regulations related to financial products and services",
      "date_range": {
        "start_date": "2026-01-30T00:00",
        "end_date": "2026-02-01T00:00"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Example response theme={null}
  {
    "id": 12345,
    "categories": [74],
    "context": "User needs to keep track of financial services regulations in the UK",
    "filter_prompt": "Policies related to financial market stability and supervision of financial institutions\nConsumer protection regulations related to financial products and services",
    "edit_prompt": "",
    "created_at": "2026-02-01T12:00:00Z",
    "language": "en-us",
    "custom_summarize": false,
    "n_potential": 0,
    "n_processed": 0,
    "error": null,
    "date_range": {
      "start_date": "2026-01-30T00:00:00+00:00",
      "end_date": "2026-02-01T00:00:00+00:00"
    },
    "returned_up_to_idx": 0,
    "uuid": "90df802d-c875-4dd7-830a-99242cfd74e0",
    "labels": {},
    "is_test": false
  }
  ```
</ResponseExample>

## Test mode

Use `is_test: true` to test your integration without running a source search. The endpoint still validates the request body the same way it does for a normal Advanced Search request.

In test mode, `POST /search/` returns a dummy Search object with an `id`. Retrieve that Search with [Get Search](/api-reference/endpoint/get-search) to read the dummy `search_results` and `edited_results`. The API does not run `edit_prompt` in test mode. If you include `test_data.edited_results`, that value is stored exactly as provided.

```json Example test request body theme={null}
{
  "categories": [74],
  "context": "User needs to keep track of financial services regulations in the UK",
  "filter_prompt": "Policies related to financial market stability and supervision of financial institutions",
  "edit_prompt": "Return a JSON report grouped by regulator",
  "date_range": {
    "duration_seconds": 604800
  },
  "is_test": true,
  "test_data": {
    "search_results": [
      {
        "url": "https://example.com/regulatory-update",
        "title": "Example regulatory update",
        "text": "Example source text for testing.",
        "summary": "Example summary returned in test mode.",
        "date": "2026-02-03",
        "type": "ARTICLE",
        "extra_data": {},
        "search_topics": [0],
        "jurisdictions": ["UK"]
      }
    ],
    "edited_results": {
      "report_title": "Example financial services report",
      "items": [
        {
          "regulator": "Example regulator",
          "summary": "Example custom report item."
        }
      ]
    }
  }
}
```

The create response contains the dummy Search object's `id`. Use that `id` to retrieve the stored dummy data:

```bash Retrieve test Search theme={null}
curl -X GET "https://parsagon.io/api/events/v1/search/12345/" \
  -H "Authorization: Token YOUR_API_KEY_HERE"
```

```json Example test retrieval response theme={null}
{
  "id": 12345,
  "categories": [74],
  "context": "User needs to keep track of financial services regulations in the UK",
  "filter_prompt": "Policies related to financial market stability and supervision of financial institutions",
  "edit_prompt": "Return a JSON report grouped by regulator",
  "is_test": true,
  "search_results": [
    {
      "url": "https://example.com/regulatory-update",
      "title": "Example regulatory update",
      "text": "Example source text for testing.",
      "summary": "Example summary returned in test mode.",
      "date": "2026-02-03",
      "type": "ARTICLE",
      "extra_data": {},
      "search_topics": [0],
      "jurisdictions": ["UK"]
    }
  ],
  "edited_results": {
    "report_title": "Example financial services report",
    "items": [
      {
        "regulator": "Example regulator",
        "summary": "Example custom report item."
      }
    ]
  },
  "error": null
}
```