A poll trigger lets a workflow watch an HTTP endpoint you control and start a cloud run for every new item it returns: a queue of support tickets, a feed of webhook events you've buffered, anything you can put behind a GET with a cursor.

The endpoint contract

Your endpoint answers:

GET /poll?cursor=<opaque>&limit=50
<your configured header name>: <encrypted value>

200 -> {
  "items": [
    {"id": "...", "kind": "...", "occurred_at": "...", "data": { ... }}
  ],
  "cursor": "<opaque, echoed back next poll>",
  "has_more": false
}

id is the idempotency key. Proliferate uses it to make sure the same item never spawns two runs, even across retries.
data is checked against the workflow's inputs before an item ever reaches an agent. See item shape below.
cursor is opaque to Proliferate. You mint it, you interpret it, Proliferate just stores it and echoes it back on the next poll.

Cursor and dedup

Each poll trigger has one cursor. Proliferate polls, gets a page of items, and records the page and its new cursor in one transaction:

Each item ID is recorded as spawned, invalid, or errored before the page's cursor commits. If the transaction fails, the old cursor is polled again and the item-ID seen set absorbs any replay.
has_more: true does not cause another request in the same cycle. The next due poll uses the stored cursor to fetch the next page.
If the same id shows up again on a later poll (your feed replayed it, or you're re-testing), Proliferate recognizes it as already-seen and skips it. No second run is created.

Use a stable ID and cursor. Deduplication prevents a repeated ID from starting a second run, but it also means an item recorded as invalid or errored is considered seen and will not retry automatically.

Item shape comes from the workflow's inputs

There's no separate schema editor for poll items. The shape Proliferate expects in data is derived straight from the workflow's declared inputs: each input becomes a property, typed to match (a choice input also carries its allowed values). An input only has to appear in data if it isn't already covered by a static preset or a default value on the trigger.

The schema is derived when you save the trigger. If you later change the workflow's inputs, save the trigger again to refresh and revalidate that schema.

Starting a workflow from a poll feed

You don't need an existing workflow to try this out. From the workflows home screen, From a poll feed opens a small modal asking for just the poll URL and an optional auth header. No workflow, inputs, or trigger exist yet.

Submitting it calls /init on your endpoint and, from the sample item it returns, derives a starting set of inputs (one per field in data, typed to match: text, number, or boolean) and hands you straight into the workflow editor with those inputs already declared. From there it's a normal workflow: add steps, adjust or remove the derived inputs, save.

Only supported scalar fields become inputs. Arrays, objects, and null values are shown as skipped so you can add the right inputs by hand.

A bad response here (endpoint unreachable, wrong path, or not JSON) fails right in the modal; nothing gets created. An endpoint that's reachable but returns no sample item still works, just with no inputs derived. Add them by hand in the editor.

This only seeds a starting point. It doesn't create a poll trigger by itself; add one from the editor once the workflow looks right (see below).

Registering a poll trigger

From the workflow's editor, add a poll trigger and fill in:

URL — the base poll endpoint (http/https only).
Auth header (optional) — a header name and value Proliferate sends on every poll. The value is encrypted at rest; leaving it blank on an update keeps whatever's already stored.
Interval — how often to poll, subject to a minimum floor so a misconfigured trigger can't hammer your endpoint.
Static input presets — values for inputs that don't vary per item (a repo name, a project id). A preset is the base value; if an item's data also carries that field by name, the item's value wins for that run. An input with no preset and no default is required in every item's data.

Saving a poll trigger runs setup validation first, against a reserved path on your endpoint. See below for what that checks and why it exists before the trigger ever polls for real.

Setup: what /init checks

A poll trigger only works if what your endpoint returns actually matches what the workflow expects to receive. Catching that mismatch after the trigger is live means a broken endpoint silently produces rejected items (or worse, wrong ones) every polling cycle, so Proliferate checks it once, at save time, instead.

Your endpoint should also serve <poll-url>/init, returning sample items in the same shape a real poll response would. Proliferate calls it at trigger create or update, checking each sample item's data against the workflow's derived input schema field by field, and again on re-validation. If you change the workflow's inputs later, the next time you save the trigger, setup re-checks the still-configured endpoint against the new shape before the trigger is trusted again. /init is reserved for setup and re-validation only; actual poll cycles always hit the real feed URL, never /init.

There are two different ways an /init call can turn out, and they're not the same:

Unreachable, non-200, or malformed (endpoint down, wrong path, timeout, a response Proliferate can't parse) is treated as a broken endpoint. The save fails outright with poll_probe_failed rather than saving something unverifiable.
Reachable but returns zero sample items (a 200 with an empty item list) passes. There's nothing to check it against, so an endpoint that legitimately has no sample data yet doesn't block you from saving.

If the sample item's data doesn't match, the save fails outright with poll_signature_mismatch and the whole field-by-field diff, not just the first bad field, so you can fix everything in one pass instead of playing whack-a-mole.

If items are getting rejected

Check the trigger's item schema (derived from the workflow's inputs) against what your endpoint actually returns in data. A missing required field or a mismatched type fails per-item, not the whole poll cycle.
A rejected item is recorded and does not retry on its own. Other items in the page continue processing, and the page cursor still advances. Fix the item at the source with a new ID, or adjust the workflow inputs and resave the trigger if the schema is wrong.
If a valid item's run cannot start, the item is recorded as errored and is also not retried automatically. Later items in the page continue.
If fetching or parsing the whole page fails, the cursor stays unchanged and the trigger retries that page at the next interval.
If nothing is polling at all, re-check the endpoint URL and auth header first; a poll_probe_failed at setup time usually means the trigger was never allowed to save with a broken endpoint in the first place.

Polling triggers