Job Watcher - Crustdata Docs

Use this when you want new postings to keep arriving on their own: roles at your target accounts, hiring signals in a market, or every opening in a function, with no manual re-running. A Job Watcher turns a Job Search filter into a recurring feed. Each run re-evaluates your filters and delivers only the new matching jobs. This page walks you through the basics: your first watch, the response shape, the notification shape, and filters that reach into the company and person datasets, then folds in worked recipes you can copy, paste, and adapt. Every request goes to the same endpoint:

POST https://api.crustdata.com/watch/job/search

Replace YOUR_API_KEY in each example with your actual API key. All requests require the x-api-version: 2025-11-01 header.

Request body

Parameter	Type	Required	Default	Description
`filters`	object	Yes*	-	A single filter condition or a nested `and`/`or` group, identical to Job Search.
`realtime_filters`	object	No	-	What the live search is asked for on a realtime watch. Requires `config.is_realtime`.
`config`	object	Yes	-	Schedule and per-run caps. See config below.
`notifications`	object[]	Yes	-	Delivery channels. May be `[]` for a pull-only watch you read from the run endpoints.
`fields`	string[]	No	standard set	Dot-path fields or field groups to include in each delivered job.
`sorts`	object[]	No	-	Delivery order within a run, for example `[ { "field": "metadata.date_added", "order": "desc" } ]`.
`on`	string[]	No	`["added"]`	Which membership transitions notify you. Only `added` is supported today.
`overflow_policy`	string	No	`redeliver`	What happens to matches beyond `max_results_per_run`. `redeliver` holds them for a later run, `drop` discards them.

* Optional on a realtime watch, where realtime_filters is what the watch runs on and filters narrows the result.

`config`

Parameter	Type	Required	Default	Description
`trigger`	object	Yes	-	`{ "type": "interval", "every_hours": N }`. How often the watch runs, for example `1`, `6`, `24`, `168`.
`max_results_per_run`	integer	No	`25`	Jobs delivered per run, `1` to `1000`. The baseline run is always capped at 5.
`preferred_hour`	integer	No	-	Hour of day in UTC (`0` to `23`) to prefer for the run.
`expires_at`	string	No	-	Auto-expire date, `YYYY-MM-DD`. The watch stops running after it.
`payload_delivery_type`	string	No	`"inline"`	`"inline"` or `"link"`. See Payload delivery.
`is_realtime`	boolean	No	`false`	Run the search against a live search rather than the index. Requires `realtime_filters`, and forces `every_hours` to `24` or more. See Realtime discovery watches.

Bound your filter by posting date. A leaf like { "field": "metadata.date_added", "type": "=>", "value": "2026-08-01" } keeps the watch focused on fresh postings instead of the full historical pool. Thirty days back is a good default.

Response body

Create returns the whole watch, so you can confirm what was stored before the baseline run starts.

Field	Type	Description
`id`	integer	The watch’s id. Use it on every management and run-history path.
`kind`	string	`"discovery"`.
`dataset`	string	`"job"`.
`status`	string	`active`, `paused`, `suspended`, `expired`, or `cancelled`.
`filters`	object	The saved filter, as sent.
`sorts`	array or null	The saved sort rules.
`fields`	array or null	The saved projection. `null` means the standard set.
`config`	object	The stored schedule and caps.
`notifications`	object[]	The configured channels. A stored channel secret is never returned.
`created_at`	string	When the watch was created.
`last_run_at`	string or null	When the watch last ran. `null` until the baseline run completes.
`last_notified_at`	string or null	When the watch last delivered a notification.
`notifications_count`	integer	All-time count of jobs this watch has delivered.
`credits_consumed`	number	All-time credits this watch has spent.

Rate limits and credits

Pricing: the first run is a free baseline (a sample of up to 5 matches), then 0.5 credits per new job delivered, or 5 credits on a realtime watch. A run that finds nothing new costs nothing.

Rate limit: 10 requests per minute on /watch/job/search. Each watch path keeps its own budget. See Rate limits.
Baseline limit: 500,000 jobs. See How a watch runs.
Watched list: filters are fixed once created. To change what you watch for, create a new watch.

Examples

Titles, locations, company size, recency, cross-dataset recipes.

Cross-dataset filters

Filter a job watch on the company behind the posting or the people it employs.

Job Search reference

Every filter field, operator, and value.

Your first watch: a role, a country, a company size

The simplest watch is a search filter plus a schedule and one channel. This one delivers new software engineer roles in the United States at companies of 3,000 or more, newest first.

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "job_details.title", "type": "(.)", "value": "software engineer" },
        { "field": "location.country", "type": "=", "value": "United States" },
        { "field": "company.headcount.total", "type": "=>", "value": 3000 }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 }, "max_results_per_run": 25 },
    "sorts": [ { "field": "metadata.date_added", "order": "desc" } ],
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

{
    "id": 50973,
    "kind": "discovery",
    "dataset": "job",
    "api_version": "2025-11-01",
    "config_version": "2025-11-01",
    "status": "active",
    "filters": {
        "op": "and",
        "conditions": [
            { "field": "job_details.title", "type": "(.)", "value": "software engineer" },
            { "field": "location.country", "type": "=", "value": "United States" },
            { "field": "company.headcount.total", "type": "=>", "value": 3000 }
        ]
    },
    "on": ["added"],
    "sorts": [ { "field": "metadata.date_added", "order": "desc" } ],
    "fields": null,
    "config": {
        "trigger": { "type": "interval", "every_hours": 24 },
        "max_results_per_run": 25,
        "expires_at": null,
        "preferred_hour": null,
        "payload_delivery_type": "inline"
    },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ],
    "created_at": "2026-09-03T07:33:10.127537Z",
    "last_run_at": null,
    "last_notified_at": null,
    "notifications_count": 0,
    "credits_consumed": 0
}

Understanding the response

id: the handle for everything else. Pause, reconfigure, cancel, and read run history all take it.
status: active the moment the watch is created. A run is suspended by the system rather than half-delivered when your balance is too low.
last_run_at: null until the baseline run completes, usually within seconds.
sorts: sets the delivery order within a run. It does not change which jobs are new, only which ones you see first when a run is capped.

How a watch runs

Create the watch

POST your filters, a config, and one or more notifications channels. The response returns the whole watch, including its id.

Baseline run (free)

The first run happens within seconds and delivers a free sample of up to 5 matches so you can confirm the setup and payload shape. No credits are charged. Behind that sample, the baseline reads your entire match set to record what already exists.

Recurring runs

On the schedule you set (every_hours), the watcher re-runs your filters and delivers jobs new since the previous run, up to max_results_per_run. You are charged 0.5 credits per job delivered.

Baseline limit: 500,000 jobs. The baseline run only delivers 5, but it reads your entire match set to record what already exists. That read is capped at 500,000, and we check it when you create the watch, so a broader filter comes back 400 and you narrow it before anything runs. The cap applies to the baseline alone. Later runs deliver whatever newly matches, bounded by config.max_results_per_run.

What a notification looks like

When a run has matches, we POST this body to each channel. Discovery records arrive under results.added, each carrying the posting, the company, and the location.

Webhook POST body

{
  "metadata": {
    "watch_id": 50973,
    "kind": "discovery",
    "dataset": "job",
    "api_version": "2025-11-01",
    "run_id": 64210,
    "notification_id": "ntf_64210",
    "delivered_at": "2026-09-03T07:35:04.000000Z",
    "summary": { "delivered": 1, "total_count": 1, "max_results_per_run": 25, "truncated": false },
    "payload_delivery": { "type": "inline" }
  },
  "results": {
    "added": [
      {
        "job_details": {
          "title": "Backend Engineer, Vehicle Software",
          "url": "https://www.example-jobs.com/postings/4448814407",
          "category": "Engineering",
          "workplace_type": "On-site",
          "employment_type": "FULL_TIME"
        },
        "company": { "basic_info": { "name": "Tesla", "primary_domain": "tesla.com", "crustdata_company_id": 1034595 } },
        "location": { "raw": "Palo Alto, California, United States", "country": "United States" },
        "metadata": { "date_added": "2026-08-04T05:32:47" }
      }
    ]
  }
}

Response trimmed for clarity.

Each delivered job carries company.basic_info.crustdata_company_id, which is the handle for pulling the company’s own profile with Company Enrich. summary.truncated is true when the run matched more jobs than max_results_per_run allowed. With the default overflow_policy: "redeliver" the overflow is held back and arrives on a later run rather than being lost.

overflow_policy is accepted on create but is not echoed in the watch object, so a GET will not show you which policy a watch is on. Record it on your side if you need to know.

Realtime watches

A discovery watch reads the Crustdata index. A realtime watch searches the web live on every run instead, so it finds postings as they appear rather than waiting for our index to pick them up. Turn one on with config.is_realtime: true. The watch then takes two filter trees instead of one.

The contract

Key	When you send it	Who answers it	What it holds
`config.is_realtime`	To make the watch realtime	Nothing. It is the switch.	`true`. No other value and no other key turns a watch realtime.
`realtime_filters`	Required once `is_realtime` is `true`	The live search	Only the posting fields listed below.
`filters`	Optional on a realtime watch, required on any other	The Crustdata index	Everything else, in the full Job Search grammar.

The live search runs first. filters then checks what it returned, so it can only drop postings. It never adds any. Send one key without the other and the create fails. Neither can change afterwards: a PATCH carrying is_realtime or realtime_filters is refused, so you make a new watch instead.

Filter fields the live job search accepts

The live job search is a keyword, a location, and the employer’s industry. These are the only field paths realtime_filters takes on a job watch. Anything else, including job_details.workplace_type, job_details.employment_type, and salary, belongs in filters.

Field	Operators	Values
`job_details.title`	`=` `(.)`	Free text keyword. `=` matches exactly, `(.)` matches loosely.
`content.description`	`=` `(.)`	Free text keyword.
`location.country`	`=` `in`	A country name.
`location.state`	`=` `in`	A state or region name.
`location.city`	`=` `in`	A city name.
`company.basic_info.industries`	`=` `in`	An industry name.

Name the country alongside a state, and the country and state alongside a city: the coarser levels are what place the finer name. When you give all three, the watch searches on the most specific one. One keyword per watch. job_details.title and content.description feed the same free-text box, so naming both folds them into a single expression rather than two filters. Write the boolean yourself when you want control over it:

{ "field": "job_details.title", "type": "(.)", "value": "\"machine learning\" OR \"applied science\"" }

A multi-word value is quoted for you, so the words are matched together rather than separately. You write the same values here as you do in filters. Use Job Autocomplete to find them, exactly as you would for an index-tier watch.

Tree shape

The live search takes an AND of filters, with OR only between values of one filter, so realtime_filters accepts:

A top-level and group of leaves, or a single bare leaf.
An or group inside it only when every leaf names the same field and uses an include operator (=, in, (.)). Use it as a value list.
No nested and groups.
No sorts on the watch at all. A live search has no stable order, so a job watch that sorts newest-first has to stay on the index tier.
One keyword, as above.

The live job fields take no negation operators at all. Put every not_in and != in filters.

What goes in `filters`

Everything the live search cannot be asked. filters keeps the full Job Search grammar, so put here:

Any job field not in the table above, including job_details.workplace_type, job_details.employment_type, and salary.
or across two different fields, nested groups, and every negation operator.
Conditions about the employer, such as company.headcount.range. Name one in realtime_filters and the create is refused. See Filters from other datasets.

Leave filters out and nothing is dropped. Every posting the live search returns is delivered.Send filters and it is checked against our index, which can only answer for a posting the index already holds. So a posting the live search just found that has not reached the index yet is dropped rather than delivered unchecked. Add a condition to filters when you would rather miss a posting than deliver one nobody checked.

You cannot write one or spanning both trees. They are separate keys, which matches what the watch can do: a posting the live search never returned cannot be brought back by a later stage.

Limits


How often it runs	Once a day at most. `config.trigger.every_hours` must be `24` or more.
How many postings it may follow	No limit checked at creation. The live job search pages through results instead of counting them, so there is no total to check your filters against. A broad watch is accepted and simply costs more, since each run bills per new posting. Narrow it yourself.
What a posting costs	5 credits, against 0.5 on an index watch. The first run is still a free sample of up to 5, and a run that finds nothing new costs nothing.
What comes back	Only the fields a live posting carries. Leave `fields` out and the create response lists them for you.

Realtime examples

A role and a country, narrowed to remote

The live search handles the title, the country, and the employer’s industry. job_details.workplace_type has no live filter behind it, so it narrows afterwards.

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "realtime_filters": {
      "op": "and",
      "conditions": [
        { "field": "job_details.title", "type": "(.)", "value": "Staff Machine Learning Engineer" },
        { "field": "location.country", "type": "in", "value": ["United States"] },
        { "field": "company.basic_info.industries", "type": "in", "value": ["Software Development"] }
      ]
    },
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "job_details.workplace_type", "type": "in", "value": ["Remote"] }
      ]
    },
    "config": { "is_realtime": true, "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

{
    "id": 52317,
    "kind": "discovery",
    "dataset": "job",
    "api_version": "2025-11-01",
    "status": "active",
    "filters": {
        "op": "and",
        "conditions": [
            { "field": "job_details.workplace_type", "type": "in", "value": ["Remote"] }
        ]
    },
    "realtime_filters": {
        "op": "and",
        "conditions": [
            { "field": "job_details.title", "type": "(.)", "value": "Staff Machine Learning Engineer" },
            { "field": "location.country", "type": "in", "value": ["United States"] },
            { "field": "company.basic_info.industries", "type": "in", "value": ["Software Development"] }
        ]
    },
    "on": ["added"],
    "sorts": null,
    "fields": [
        "job_details.title",
        "job_details.category",
        "job_details.url",
        "job_details.workplace_type",
        "job_details.reposted_job",
        "job_details.employment_type",
        "content.description",
        "location.raw",
        "location.country",
        "metadata.date_added",
        "metadata.date_updated",
        "company.basic_info.name",
        "company.basic_info.professional_network_id"
    ],
    "config": {
        "trigger": { "type": "interval", "every_hours": 24 },
        "max_results_per_run": 25,
        "payload_delivery_type": "inline",
        "is_realtime": true,
        "refresh_frequency_days": 1
    },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
}

Response trimmed to the keys under discussion. fields comes back filled with everything a live posting carries.

A technology in the description, folded with the title

Both keyword fields feed one box, so this pair goes out as a single expression.

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "realtime_filters": {
      "op": "and",
      "conditions": [
        { "field": "content.description", "type": "(.)", "value": "Kubernetes" },
        { "field": "job_details.title", "type": "(.)", "value": "Platform Engineer" },
        { "field": "location.country", "type": "in", "value": ["United States"] }
      ]
    },
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "job_details.employment_type", "type": "in", "value": ["Full-time"] }
      ]
    },
    "config": { "is_realtime": true, "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": []
  }'

{
    "id": 52318,
    "kind": "discovery",
    "dataset": "job",
    "status": "active",
    "filters": {
        "op": "and",
        "conditions": [
            { "field": "job_details.employment_type", "type": "in", "value": ["Full-time"] }
        ]
    },
    "realtime_filters": {
        "op": "and",
        "conditions": [
            { "field": "content.description", "type": "(.)", "value": "Kubernetes" },
            { "field": "job_details.title", "type": "(.)", "value": "Platform Engineer" },
            { "field": "location.country", "type": "in", "value": ["United States"] }
        ]
    },
    "config": {
        "trigger": { "type": "interval", "every_hours": 24 },
        "max_results_per_run": 25,
        "payload_delivery_type": "inline",
        "is_realtime": true,
        "refresh_frequency_days": 1
    },
    "notifications": []
}

Response trimmed to the keys under discussion. Each term is also re-checked against its own field on the postings that come back, so a description match does not pass as a title match.

Every posting in one city, with no keyword

A keyword is optional. A location and an industry are enough on their own, which gives you the whole hiring feed for a market rather than one role in it.

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "realtime_filters": {
      "op": "and",
      "conditions": [
        { "field": "location.city", "type": "in", "value": ["Seattle"] },
        { "field": "location.state", "type": "in", "value": ["Washington"] },
        { "field": "location.country", "type": "in", "value": ["United States"] },
        { "field": "company.basic_info.industries", "type": "in", "value": ["Software Development"] }
      ]
    },
    "config": { "is_realtime": true, "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": []
  }'

{
    "id": 52476,
    "kind": "discovery",
    "dataset": "job",
    "status": "active",
    "filters": null,
    "realtime_filters": {
        "op": "and",
        "conditions": [
            { "field": "location.city", "type": "in", "value": ["Seattle"] },
            { "field": "location.state", "type": "in", "value": ["Washington"] },
            { "field": "location.country", "type": "in", "value": ["United States"] },
            { "field": "company.basic_info.industries", "type": "in", "value": ["Software Development"] }
        ]
    },
    "config": {
        "trigger": { "type": "interval", "every_hours": 24 },
        "max_results_per_run": 25,
        "payload_delivery_type": "inline",
        "is_realtime": true,
        "refresh_frequency_days": 1
    },
    "notifications": []
}

Response trimmed to the keys under discussion. Nothing checks how broad a job watch is at creation, so a feed this wide is accepted and simply bills per new posting.

Realtime errors

Every failure is a 400 in the usual envelope. error.metadata[].field tells a realtime_filters problem from a filters one.

What you did	What comes back
`is_realtime: true`, no `realtime_filters`	`realtime_filters is required when config.is_realtime is true...`
`realtime_filters`, no `is_realtime`	`realtime_filters needs config.is_realtime: true...` plus `filters` now required
A field the live job search has no filter for	`'<field>' is not something the live search can be asked for. Move it to 'filters'...`
An `or` across two different fields	`An 'or' is available only across values of one field.`
A nested `and` group	`Nested 'and' groups are not available.`
`sorts` on a realtime watch	`The live search has no stable sort order.`
`every_hours` under `24`	`config.trigger.every_hours must be at least 24...`
`config.refresh_frequency_days`, any value	`config.refresh_frequency_days is not accepted on a discovery watch...`
An employer condition in `realtime_filters`	`'<field>' is not something the live search can be asked for. Move it to 'filters'...`
`PATCH` carrying `is_realtime` or `realtime_filters`	`config.<key> cannot be changed on a discovery watch. Create a new watch.`

sorts on a realtime watch

A job watch that sorts newest-first cannot be realtime. Drop sorts, or drop is_realtime and stay on the index tier.

400

{
    "error": {
        "type": "invalid_request",
        "message": "realtime_filters: 'sorts' is not something the live search can be asked for. The live search has no stable sort order.",
        "metadata": [
            {
                "field": "realtime_filters",
                "type": "unsupported",
                "message": "realtime_filters: 'sorts' is not something the live search can be asked for. The live search has no stable sort order."
            }
        ]
    }
}

config.refresh_frequency_days on a discovery watch

A discovery watch picks how it reads with is_realtime, so it has no freshness cadence of its own. The key is refused on both tiers, whatever value you give it.

400

{
    "error": {
        "type": "invalid_request",
        "message": "config.refresh_frequency_days is not accepted on a discovery watch. Use config.is_realtime: true for the live tier, and leave it out for the index tier.",
        "metadata": [
            {
                "field": "config.refresh_frequency_days",
                "type": "extra_forbidden",
                "message": "config.refresh_frequency_days is not accepted on a discovery watch. Use config.is_realtime: true for the live tier, and leave it out for the index tier."
            }
        ]
    }
}

Runs scheduled more often than daily

400

{
    "error": {
        "type": "invalid_request",
        "message": "config.trigger.every_hours must be at least 24 when refresh_frequency_days is 1: a live run fetches from the source and is billed per new record. Use refresh_frequency_days 30 to run more often.",
        "metadata": [
            {
                "field": "config.trigger.every_hours",
                "type": "greater_than_equal",
                "message": "config.trigger.every_hours must be at least 24 when refresh_frequency_days is 1: a live run fetches from the source and is billed per new record. Use refresh_frequency_days 30 to run more often."
            }
        ]
    }
}

Delivery channels

Every watch takes a notifications array. Add one or more and matches fan out to all of them.

{ "type": "webhook", "url": "https://your-app.com/webhooks/crustdata", "headers": { "X-Watch-Name": "swe-us-3000" } }

{ "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" }

{ "type": "email", "to": ["you@company.com"] }

{ "type": "google_chat", "url": "https://chat.googleapis.com/v1/spaces/…" }

[
  { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" },
  { "type": "email", "to": ["you@company.com"] }
]

[]

A Slack channel must be a genuine Slack incoming webhook (https://hooks.slack.com/services/…). Any other URL will fail delivery.

An empty notifications array is valid. The watch runs and records everything, pushes nothing, and you read each run from the run endpoints.

Where the records travel

By default a run’s jobs arrive inside the notification, under results. Set config.payload_delivery_type to "link" and the body carries no records at all. It carries metadata.payload_delivery.url instead, a pre-signed S3 URL for one NDJSON file holding every record of that run. Switch when a run can outgrow what your receiver accepts. An AWS Lambda proxy integration caps a request at 6 MB and an ALB target at 1 MB, and an oversize body is refused whole.

curl --request PATCH \
  --url https://api.crustdata.com/watch/job/search/50973 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "config": {
      "trigger": { "type": "interval", "every_hours": 24 },
      "payload_delivery_type": "link"
    }
  }'

Every channel on the watch gets the same link, and the run-summary endpoint serves the same file. Read metadata.payload_delivery.type rather than testing for results: a link watch falls back to an inline body if the file cannot be written. See Payload delivery for the file format, the link lifetime, and the errors.

Filters from other datasets

A job watch is not limited to job fields. Drop a company field or a person field into the same flat conditions list and the watch filters on the company behind the posting:

{
  "op": "and",
  "conditions": [
    { "field": "headcount.growth_percent.6m", "type": ">", "value": 50 },
    { "field": "job_details.category",        "type": "=", "value": "Sales" }
  ]
}

Sales roles at companies that grew headcount more than 50% in six months. Some company attributes are carried on each job record already, under a company. prefix: funding stage, headcount, industry, and head office all work as company.funding.last_round_type, company.headcount.total, and so on. Growth rate, founding year, competitor list, and the rest of the company vocabulary are not carried there, and those now work too. Use the unprefixed Company Search name for them.

Cross-dataset filters are a discovery watch feature, which is what a job watch is. There is no job entity watcher: a posting does not change, it appears and disappears.

What you can combine

A job watch can also filter on	Joined through
Company fields	The company posting the job
Person fields	The person’s current employer, matched to the posting company

A single watch can pull from all three datasets at once.

People join through their current employer only. A filter on a past employer still selects the right people, but the company it points at is where they work now. “Jobs at companies that hired away from Acme” means companies that currently employ someone whose earlier experience was at Acme.

The rules in one place

Field names decide the dataset, so there is nothing to declare: job_details.title is a job field, headcount.total a company field, and experience.employment_details.current.title a person field. Conditions from another dataset are answered first, come back as a set of company IDs, and narrow your watch through the posting company. Delivery, deduplication, per-run caps, and the payload shape are unchanged, and you are still charged 0.5 credits per job. Reading the other dataset is free. A cross-dataset condition may cover at most 1,000,000 companies, checked at creation and measured on the cross-dataset conditions alone, so adding a job condition does not get you past it. Row-level negation (!=, not_in, (!), not_contains, geo_exclude) is rejected on a condition from another dataset, because it matches jobs whose company has some other matching row rather than none. Nothing beyond the company. fields already on the job record comes back with a cross-dataset filter. For the rest of the company’s profile, call POST /company/enrich yourself with the delivered company.basic_info.crustdata_company_id.

A condition that matches nothing because of a bad value is accepted at creation and then quietly never fires. {"field": "job_details.employment_type", "type": "=", "value": "Full-time"} matches zero jobs, because the stored value is FULL_TIME. Run every condition through Job Search first and confirm total_count is not zero.

See Cross-dataset filters for the join rules, the grouping semantics, the lookup fields for that follow-up call, the limits with their exact errors, and how timing and deduplication change.

Test your receiver before a run fires

Push one sample notification through a watch to verify your receiver end to end, without waiting for a posting to appear.

POST https://api.crustdata.com/watch/job/search/{watch_id}/test

The sample is built from real current matches of the watch’s own filter and shaped through the same processor a real run uses, so the payload is identical to production apart from metadata.test: true. The call records nothing: it creates no run, does not advance the seen set, and costs no credits.

Field	Type	Description
`notification_endpoint`	string	Deliver this one test to a URL you control instead of the watch’s channels. Must be a public `http(s)` URL.
`count`	integer	Deliver `N` sample jobs (`1` to `25`) in one envelope. Default `1`.
`deliver`	boolean	Send `false` to get the envelope back without any outbound request.

curl --request POST \
  --url https://api.crustdata.com/watch/job/search/50973/test \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{ "notification_endpoint": "https://your-server.example.com/webhook", "count": 3 }'

A watch whose filter currently matches nothing has nothing to sample, and the call returns 400 with This watch's filter currently matches 0 records - nothing to sample. That is a useful signal in itself: a watch that cannot produce a sample will not produce a delivery either.

Manage a watch

Action	Request
List your watches	`GET /watch/job/search?status=active&limit=50&offset=0`
Get one	`GET /watch/job/search/{id}`
Pause / resume	`PATCH /watch/job/search/{id}` with `{ "status": "paused" }`
Reschedule	`PATCH /watch/job/search/{id}` with a new `config`
Replace the channels	`PATCH /watch/job/search/{id}` with a new `notifications`
Cancel	`DELETE /watch/job/search/{id}` → `204`

curl --request PATCH \
  --url https://api.crustdata.com/watch/job/search/50973 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{ "status": "paused" }'

curl --request DELETE \
  --url https://api.crustdata.com/watch/job/search/50973 \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-11-01'

curl --request GET \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-11-01'

filters, sorts, fields, and on are fixed once the watch exists. PATCHing any of them returns 400. To change what you watch for, create a new watch.

Read what a run delivered

Every run is readable after the fact, so a watch is never a black box between deliveries. The read paths drop the search/ segment that create and manage use.

curl --request GET \
  --url 'https://api.crustdata.com/watch/job/50973/runs?limit=20' \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-11-01'

curl --request GET \
  --url https://api.crustdata.com/watch/job/50973/runs/54811/summary \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-11-01'

runs returns each run with status, new_records_count, credits_deducted, and notification_http_status, newest first, paginated by cursor. A non-2xx notification_http_status means the run found matches and the delivery itself was rejected, so check it before concluding a quiet channel means nothing happened. summary returns one run in full: its activity log, and every delivery attempt with the jobs it carried under notifications[].payload.notifications[].record. That is the same record shape your channel receives, so the records are readable here even when no channel is configured.

Examples

Worked recipes you can copy, paste, and adapt. Each one is a full working request, verified against the live API. Swap the notification channel for your own. For the operator list, field catalog, and validation rules, see the Job Search reference.

Follow a function at recently funded companies

Bound the feed by posting date so it stays about fresh hiring, and by funding stage so it stays about companies with new budget. This watch delivers engineering roles posted since 2026-08-01 at Series A and Series B companies, to Slack.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "job_details.category", "type": "=", "value": "Engineering" },
        { "field": "metadata.date_added", "type": "=>", "value": "2026-08-01" },
        { "field": "company.funding.last_round_type", "type": "in", "value": ["series_a", "series_b"] }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" } ]
  }'

Round-type values on a job record are lowercase with underscores: series_a, series_b, seed. "Series A" matches zero jobs and the watch stays silent.

Follow remote roles at accounts you track

Name the companies by domain and let the watch tell you when they post something remote. This one checks every six hours.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "company.basic_info.primary_domain", "type": "in", "value": ["stripe.com", "figma.com"] },
        { "field": "job_details.workplace_type", "type": "=", "value": "Remote" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 6 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

job_details.workplace_type takes Remote, Hybrid, or On-site. For employment type, the stored values are uppercase with underscores, so filter on FULL_TIME rather than Full-time.

Watch full-time remote roles

Combine the two posting attributes that decide whether a role is worth surfacing to a candidate at all.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "job_details.employment_type", "type": "=", "value": "FULL_TIME" },
        { "field": "job_details.workplace_type", "type": "=", "value": "Remote" },
        { "field": "job_details.category", "type": "=", "value": "Engineering" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "sorts": [ { "field": "metadata.date_added", "order": "desc" } ],
    "notifications": [ { "type": "email", "to": ["you@company.com"] } ]
  }'

Watch a radius around a city

The geo_distance operator works on location and location.raw, which catches the metro rather than one city string. This watch delivers sales roles within 50 km of New York.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        {
          "field": "location.raw",
          "type": "geo_distance",
          "value": { "location": "New York, NY", "distance": 50, "unit": "km" }
        },
        { "field": "job_details.category", "type": "=", "value": "Sales" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

geo_distance and geo_exclude only work on location and location.raw. Using either on another field, or sending a malformed geo value, returns 500.

Hunt for a keyword in the job description

content.description is full-text, so it catches requirements a title never mentions. This watch delivers engineering roles whose description mentions Kubernetes.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "content.description", "type": "(.)", "value": "kubernetes" },
        { "field": "job_details.category", "type": "=", "value": "Engineering" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 }, "max_results_per_run": 100 },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

Follow a title in one city

location.city is the normalized city facet, so it does not need the full raw location string. This watch delivers account executive roles in London.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "location.city", "type": "=", "value": "London" },
        { "field": "job_details.title", "type": "(.)", "value": "account executive" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

Follow roles at well-funded employers

company.funding.total_investment_usd rides on the job record, so this needs no cross-dataset join. This watch delivers US engineering roles at companies that have raised more than $50M.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "company.funding.total_investment_usd", "type": ">", "value": 50000000 },
        { "field": "job_details.category", "type": "=", "value": "Engineering" },
        { "field": "location.country", "type": "=", "value": "United States" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

Drop the country condition and this filter matches 1,030,186 jobs, past the baseline limit, and the create comes back

This watch would follow 1,030,186 records, more than the 500,000 a single           watch can track. Please narrow your filters.

Reach for the company. prefix first. It reads the copy already on the job record, with no join. Use the unprefixed Company Search name only for the attributes the job record does not carry, like growth rate or founding year.

Cross-dataset: sales roles at fast-growing companies

Headcount growth is not carried on the job record, so this pairing needs the company dataset. This watch delivers sales roles at companies that grew more than 50% in six months.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "headcount.growth_percent.6m", "type": ">", "value": 50 },
        { "field": "job_details.category",        "type": "=", "value": "Sales" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

Cross-dataset: roles at recently founded companies

Founding year is not on the job record either. It is also very broad, so pair it with a second company condition, not just a job one.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "basic_info.year_founded", "type": ">",   "value": 2020 },
        { "field": "headcount.total",         "type": "=>",  "value": 50 },
        { "field": "job_details.title",       "type": "(.)", "value": "account executive" },
        { "field": "location.country",        "type": "=",   "value": "United States" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

The million-company ceiling is measured on the company conditions alone, so a job condition does not help you past it. basic_info.year_founded > 2020 on its own reaches roughly four million companies and is rejected with Your company filters cover more than 1,000,000 companies., followed by a suggestion to add a location, a date, or a more specific title. The headcount.total condition here is what makes it acceptable.

Cross-dataset: roles at companies hiring away from a rival

A person condition joins through the current employer, so this finds postings at companies that already employ someone from a competitor. This watch delivers software engineer roles at companies employing an ex-Stripe person.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "job_details.title",                               "type": "(.)", "value": "software engineer" },
        { "field": "experience.employment_details.past.company_name", "type": "=",   "value": "Stripe" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

Deliver a large run as a linked file

Raise the per-run cap and switch the payload to a link when a run can outgrow what your receiver accepts.

Request

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "field": "job_details.category", "type": "=", "value": "Engineering" },
        { "field": "location.country", "type": "=", "value": "United States" }
      ]
    },
    "config": {
      "trigger": { "type": "interval", "every_hours": 24 },
      "max_results_per_run": 1000,
      "payload_delivery_type": "link"
    },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'

The notification then carries metadata.payload_delivery.url, a pre-signed URL for one NDJSON file holding the whole run, and no results key. See Payload delivery.

Run a watch with no channel and pull the results

Send notifications: [] and the watch pushes nothing. It still runs on schedule, still records every match, and you read each run yourself.

curl --request POST \
  --url https://api.crustdata.com/watch/job/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": { "field": "job_details.category", "type": "=", "value": "Engineering" },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": []
  }'

curl --request GET \
  --url https://api.crustdata.com/watch/job/50973/runs/54811/summary \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-11-01'

The records are readable from summary even with no channel configured, so this is a good way to sanity-check a filter before you wire delivery to it.

Error handling

A job watch answers every failure the same way, whether you are creating a watch, editing one, testing delivery, or reading run history.

Status	Type	Common causes
`400`	`invalid_request`	An unknown filter field or operator, `filters` or `config` left out, `config.trigger.every_hours` below `1`, a `fields` entry that is not a job field path, a filter set broader than the 500,000-record baseline cap, a missing or unsupported `x-api-version`, or a `PATCH` to a key fixed at creation.
`401`	`unauthorized`	Missing or invalid API key.
`403`	`permission_error`	Your key is not entitled to the job dataset, or to a field group you named in `fields`.
`404`	`not_found`	No watch with that id on your account. The watch, test, and run paths all answer the same way.
`405`	`invalid_request`	A method the path does not serve, such as `PUT` on the create path.
`429`	`rate_limit_error`	More than 10 watch-management requests in a minute. See Rate limits.

Every watcher failure comes back in the same envelope the search and enrich APIs use, whatever the status code:

{
    "error": {
        "type": "invalid_request",
        "message": "Watch not found",
        "metadata": []
    }
}

type is the machine-readable code you branch on, message is the sentence you can show a user, and metadata carries per-problem detail when there is any. Read error.message, not the top level: there is no detail key and no non_field_errors key on any watcher response.

Every problem in one response

Validation collects every failure in one pass, so a payload with three things wrong costs one round trip rather than three. metadata carries one entry per problem, and message is those entries joined in order:

400 - three problems, one response

{
    "error": {
        "type": "invalid_request",
        "message": "config.trigger.every_hours must be an integer >= 1. on: 'removed' is not yet supported. Unknown filter field at filters.conditions[0]: 'headcount'.",
        "metadata": [
            {
                "field": "config.trigger.every_hours",
                "type": "greater_than_equal",
                "message": "config.trigger.every_hours must be an integer >= 1."
            },
            {
                "field": "on",
                "type": "unsupported",
                "message": "on: 'removed' is not yet supported."
            },
            {
                "field": "filters.conditions[0].field",
                "type": "unknown_field",
                "message": "Unknown filter field at filters.conditions[0]: 'headcount'."
            }
        ]
    }
}

Each entry carries three keys:

Key	What it holds
`field`	The request path that failed, indexed into filter and track trees, for example `filters.conditions[0].field` or `config.trigger.every_hours`.
`type`	The failure code. Mostly the vocabulary the search and enrich APIs use (`missing`, `enum`, `greater_than_equal`, `less_than_equal`, `string_type`, `int_type`, `bool_type`, `list_type`, `dict_type`, `too_long`, `date_parsing`, `extra_forbidden`, `invalid`), plus `unknown_field` and `unsupported`, which only watcher emits.
`message`	The sentence for that one problem, naming its field.

The shape of the body is checked before the rules that read across fields, so a payload that is both malformed and semantically wrong can still take two round trips: the first response names the shape problems, the second names the rules. Two is the worst case.

Exact responses

{
    "error": {
        "type": "unauthorized",
        "message": "Invalid API key in request.",
        "metadata": []
    }
}

{
    "error": {
        "type": "not_found",
        "message": "Watch not found",
        "metadata": []
    }
}

{
    "error": {
        "type": "invalid_request",
        "message": "filters: This field is required. config: This field is required.",
        "metadata": [
            { "field": "filters", "type": "missing", "message": "filters: This field is required." },
            { "field": "config", "type": "missing", "message": "config: This field is required." }
        ]
    }
}

{
    "error": {
        "type": "invalid_request",
        "message": "Missing required header: x-api-version",
        "metadata": []
    }
}

{
    "error": {
        "type": "invalid_request",
        "message": "Method \"PUT\" not allowed.",
        "metadata": []
    }
}

{
    "error": {
        "type": "rate_limit_error",
        "message": "Rate limit exceeded for this endpoint. Please write to gtm@crustdata.co.",
        "metadata": []
    }
}

A missing Authorization header and a wrong key give the same 401 body, so the response does not tell you which of the two happened.

metadata is not always a {field, type, message} triple. Three responses put a different object in it:

Invalid fields: ... carries [{ "available_fields": [...] }], the full list of field paths you may project, which runs to a few hundred entries.
Access denied to fields: ... carries [{ "denied_fields": [...], "permitted_fields": [...] }].
A test send that could not be attempted carries the delivery result it built, under delivered and envelope.

Check for the keys you expect before you iterate metadata, and fall back to error.message for anything you show a user.

A path that does not route never reaches the watcher and so never gets this envelope. POST /watch/widget/search returns the gateway’s {"error_msg": "404 Route Not Found"}, and an entity path on a dataset that has no entity watcher returns an HTML 404. Branch on the status code first, then parse.

Pricing

	Credits
First run (baseline, up to 5 matches)	Free
Each new job delivered on later runs	0.5

You are charged only for jobs actually delivered, never for a run that finds nothing new, and never for reading another dataset to narrow your filters. See Pricing for the full catalog.

What to do next

Pull the full match set: use Job Search to see everything that matches right now, not just what is new.
Look up operators and fields: see the Job Search reference for the full filter catalog.
Watch companies or people instead: the same recurring-feed model runs over companies and people.
Choose how records travel: see Payload delivery for inline versus linked NDJSON.

​Request body

​config

​Response body

​Rate limits and credits

Examples

Cross-dataset filters

Job Search reference

​Your first watch: a role, a country, a company size

​Understanding the response

​How a watch runs

​What a notification looks like

​Realtime watches

​The contract

​Filter fields the live job search accepts

​Tree shape

​What goes in filters

​Limits

​Realtime examples

​Realtime errors

​Delivery channels

​Where the records travel

​Filters from other datasets

​What you can combine

​The rules in one place

​Test your receiver before a run fires

​Manage a watch

​Read what a run delivered

​Examples

​Error handling

​Every problem in one response

​Exact responses

​Pricing

​What to do next

Request body

`config`

Response body

Rate limits and credits

Your first watch: a role, a country, a company size

Understanding the response

How a watch runs

What a notification looks like

Realtime watches

The contract

Filter fields the live job search accepts

Tree shape

What goes in `filters`

Limits

Realtime examples

Realtime errors

Delivery channels

Where the records travel

Filters from other datasets

What you can combine

The rules in one place

Test your receiver before a run fires

Manage a watch

Read what a run delivered

Examples

Error handling

Every problem in one response

Exact responses

Pricing

What to do next