Create advanced search

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"
    }
  }'

{
  "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
}

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"
    }
  }'

{
  "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
}

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

array

required

Array of category IDs to include in the search results.

string

Additional context for the AI to tailor the search and reporting (for example, your organization or focus area). Maximum 1000 characters.

string

required

A list of policy topics to search for, one per line. Longer, descriptive phrases work best. Maximum 5000 characters.

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.

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"}).

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.

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.

Show Test data fields

array

Array of search result objects to store instead of Parsagon’s built-in example results.

any

Custom edited output to store as edited_results. This value is not generated from edit_prompt; it is stored exactly as provided.

object

required

Time period to search within. May cover up to 90 days — use either start_date/end_date or duration_seconds ≤ 7776000.

Show Fixed range

string

ISO 8601 datetime (UTC). The earliest supported value is 90 days before the time of the request.

string

ISO 8601 datetime (UTC).

Show Relative duration

number

Positive number of seconds before “now” to search within (maximum 7776000).

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 and read results.

number | string

Unique identifier for the Search. Use this to retrieve results.

array

Array of category IDs used in the search.

string

Context provided in the request.

string

Filter prompt provided in the request.

string

Edit prompt provided in the request.

object

Labels provided in the request.

boolean

Whether the Search was created in test mode.

object

The date range used, containing either start_date and end_date, or duration_seconds.

string

Timestamp when the Search was created (ISO 8601, UTC).

number

Estimated number of candidate results to process.

number

Number of candidate results processed so far.

number

Internal pagination position for additional result pages.

string

Public UUID for the Search.

string | null

Error message if an error occurred; otherwise 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"
    }
  }'

{
  "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
}

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 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.

Example test request body

{
  "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:

Retrieve test Search

curl -X GET "https://parsagon.io/api/events/v1/search/12345/" \
  -H "Authorization: Token YOUR_API_KEY_HERE"

Example test retrieval response

{
  "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
}

Overview

Endpoints

AI tools

Request body

Response

Test mode

​Request body

​Response

​Test mode

Request body

Response

Test mode