curl --request POST \
  --url https://api.crustdata.com/watch/{dataset}/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "filters": {
    "op": "and",
    "conditions": [
      {
        "field": "experience.employment_details.current.title",
        "type": "(.)",
        "value": "Machine Learning Engineer"
      },
      {
        "field": "professional_network.location.raw",
        "type": "(.)",
        "value": "Paris"
      }
    ]
  },
  "config": {
    "trigger": {
      "type": "interval",
      "every_hours": 24
    },
    "max_results_per_run": 25
  },
  "notifications": [
    {
      "type": "webhook",
      "url": "https://your-app.com/webhooks/crustdata"
    }
  ]
}
'

{
  "id": 47609,
  "kind": "discovery",
  "dataset": "job",
  "api_version": "2025-11-01",
  "config_version": "2025-11-01",
  "status": "active",
  "filters": {
    "field": "experience.employment_details.current.title",
    "type": "(.)",
    "value": "Machine Learning Engineer"
  },
  "on": [
    "added"
  ],
  "sorts": [
    {
      "field": "metadata.date_added",
      "order": "desc"
    }
  ],
  "fields": [
    "<string>"
  ],
  "config": {
    "trigger": {
      "type": "interval",
      "every_hours": 24
    },
    "max_results_per_run": 25,
    "preferred_hour": 9,
    "expires_at": "2027-01-01"
  },
  "notifications": [
    {
      "type": "webhook",
      "url": "https://your-app.com/webhooks/crustdata",
      "headers": {
        "X-Watch-Name": "ml-engineers-paris"
      }
    }
  ],
  "created_at": "2026-07-16T03:16:38.351849Z",
  "last_run_at": "2026-08-04T05:32:47.000000Z",
  "notifications_count": 128,
  "credits_consumed": 64,
  "last_notified_at": "2026-08-04T05:32:47.000000Z"
}

Create a discovery watch

Creates a discovery watch: a saved search filter that re-runs on an interval and delivers the records that newly match it.

The filter uses the same syntax and the same field names as the dataset’s own search endpoint, so there is no second filter language. A leaf is { "field", "type", "value" } and groups combine leaves with { "op": "and" | "or", "conditions": [...] }. Groups nest.

The first run starts within seconds and is a free baseline capped at 5 records, so you can confirm the delivery path and the payload shape before any credit is spent. Later runs deliver up to config.max_results_per_run records each and are charged per record delivered.

A watch whose filter matches more than 500,000 records is rejected at creation: narrow the filter. A filter that names a field from another dataset is a valid cross-dataset condition rather than a typo, but row-level negation (!=, not_in, (!), geo_exclude) is rejected there because it matches subjects with some other matching row rather than subjects with none.

POST

https://api.crustdata.com

watch

{dataset}

curl --request POST \
  --url https://api.crustdata.com/watch/{dataset}/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "filters": {
    "op": "and",
    "conditions": [
      {
        "field": "experience.employment_details.current.title",
        "type": "(.)",
        "value": "Machine Learning Engineer"
      },
      {
        "field": "professional_network.location.raw",
        "type": "(.)",
        "value": "Paris"
      }
    ]
  },
  "config": {
    "trigger": {
      "type": "interval",
      "every_hours": 24
    },
    "max_results_per_run": 25
  },
  "notifications": [
    {
      "type": "webhook",
      "url": "https://your-app.com/webhooks/crustdata"
    }
  ]
}
'

{
  "id": 47609,
  "kind": "discovery",
  "dataset": "job",
  "api_version": "2025-11-01",
  "config_version": "2025-11-01",
  "status": "active",
  "filters": {
    "field": "experience.employment_details.current.title",
    "type": "(.)",
    "value": "Machine Learning Engineer"
  },
  "on": [
    "added"
  ],
  "sorts": [
    {
      "field": "metadata.date_added",
      "order": "desc"
    }
  ],
  "fields": [
    "<string>"
  ],
  "config": {
    "trigger": {
      "type": "interval",
      "every_hours": 24
    },
    "max_results_per_run": 25,
    "preferred_hour": 9,
    "expires_at": "2027-01-01"
  },
  "notifications": [
    {
      "type": "webhook",
      "url": "https://your-app.com/webhooks/crustdata",
      "headers": {
        "X-Watch-Name": "ml-engineers-paris"
      }
    }
  ],
  "created_at": "2026-07-16T03:16:38.351849Z",
  "last_run_at": "2026-08-04T05:32:47.000000Z",
  "notifications_count": 128,
  "credits_consumed": 64,
  "last_notified_at": "2026-08-04T05:32:47.000000Z"
}

Authorizations

Authorization

string

header

required

API key passed as a Bearer token in the Authorization header.

Headers

x-api-version

enum<string>

default:2025-11-01

required

API version to use. 2025-11-01 is the only accepted value. Send it on every call: it is enforced today on POST /watch/{dataset}/search, where a missing or unrecognized value returns 400, and the other watch routes accept a request without it rather than relying on that.

Available options:

2025-11-01

Example:

"2025-11-01"

Path Parameters

dataset

enum<string>

required

The dataset the watch is built on.

Available options:

person,

company,

job

Example:

"person"

Body

application/json

Body for creating a discovery watch. The dataset comes from the path, and the API version from the x-api-version header.

filters

object

required

The search filter to re-run each interval. A single leaf or a nested AND/OR group.

Option 1
Option 2

Show child attributes

config

object

required

Schedule and per-run caps for a discovery watch.

Show child attributes

sorts

object[]

Delivery order within a run, for example newest first. Sorting does not change which records are new, only the order they arrive in when a run is capped.

Show child attributes

fields

string[]

Field groups or field paths to include in each delivered record. Defaults to the dataset's standard projection. Every requested field is checked against the key's entitlements at creation, and fields does not affect what a record costs.

Example:

["basic_profile", "experience"]

enum<string>[]

Which membership transitions notify you. Only added, records that newly match, is supported today, and it is the default.

Available options:

added

Example:

["added"]

notifications

object[]

Delivery channels. May be empty for a pull-only watch, which pushes nothing and whose results you read from the run-history endpoints instead.

One delivery channel. Every channel on a watch receives every notification.

Option 1
Option 2
Option 3
Option 4

Show child attributes

overflow_policy

enum<string>

default:redeliver

What happens to new records beyond max_results_per_run. redeliver leaves the overflow unseen so it comes back in a later run. drop marks every new record seen so the overflow never returns.

Available options:

redeliver,

drop

Example:

"redeliver"

Response

The watch was created and its baseline run was scheduled.

A discovery watch, as returned by create, get, list, and update.

integer

The watch's id. Use it on every management and run-history path.

Example:

47609

kind

enum<string>

Available options:

discovery

Example:

"discovery"

dataset

enum<string>

Available options:

person,

company,

job

Example:

"job"

api_version

string

Example:

"2025-11-01"

config_version

string

Version of the stored config shape.

Example:

"2025-11-01"

status

enum<string>

Lifecycle state. suspended is set by the system, most often for an insufficient balance, and blocks status changes until it is resolved.

Available options:

active,

paused,

suspended,

expired,

cancelled

Example:

"active"

filters

object

The saved filter, as sent at creation.

Option 1
Option 2

Show child attributes

string[]

Example:

["added"]

sorts

object[] | null

Show child attributes

fields

string[] | null

config

object

Schedule and per-run caps for a discovery watch.

Show child attributes

notifications

object[]

The configured channels. A stored channel secret is never returned.

One delivery channel. Every channel on a watch receives every notification.

Option 1
Option 2
Option 3
Option 4

Show child attributes

created_at

string<date-time>

Example:

"2026-07-16T03:16:38.351849Z"

last_run_at

string<date-time> | null

When the watch last ran. null until the baseline run completes.

Example:

"2026-08-04T05:32:47.000000Z"

notifications_count

integer

All-time count of records this watch has delivered.

Example:

128

credits_consumed

number

All-time credits this watch has spent.

Example:

64

last_notified_at

string<date-time> | null

When this watch last delivered anything.

Example:

"2026-08-04T05:32:47.000000Z"