Interviews

How it works

Each interview lands in its study as a source item with a status: in_progress, processing, analyzed, insufficient (too little material to analyze), or a failure state. Only analyzed, high-quality interviews become evidence. Failed and insufficient interviews never feed a belief.

Links

Every link lives at /i/{slug} and is one of two kinds:

• Reusable link (kind: channel) — a public link for a tweet, an email blast, a help-doc footer. Uncapped by default. Every study gets a "Default" reusable link automatically.
• Single-use invite (kind: personal) — a link for one specific person, capped at one interview by default, optionally carrying that person's details baked in.

Links move through active, paused, and revoked. Pausing is reversible; revoking is permanent. A link can also carry an expiry time. Opening a link never uses it up — a use is only counted when an interview actually starts.

Metadata

Every interview can carry metadata: key/value details about the participant, like plan tier or role. Metadata is how you slice signals later ("what do enterprise users think?"), so get it on every interview you can.

Your study defines fields with human labels like First name. Each label becomes a field key: lowercased, non-alphanumerics collapsed to _, so First name becomes first_name. To prefill a value in a URL, prefix the key with f_:

https://askengine.dev/i/{slug}?f_first_name=Ada&f_email_address=ada@example.com

A prefilled field is skipped — the participant never sees the question, so a prefilled value stands. The participant only types what nothing else provided. Only declared fields are stored; unknown f_* params are ignored. On a single-use invite you can bake values into the link itself instead.

When a baked-in invite value and a query param set the same field, the baked-in value wins — the link's own value is the source of truth. One escape hatch: passing an empty value (?f_first_name=) clears a query-param prefill, and the question comes back. It can't touch a baked-in value.

Identity keys

A few field keys tell AskEngine who a participant is, so the same person across two interviews resolves to one participant. Match keys, in order: uid, then email, then email_address. Display keys, for the friendly name: name, first_name, username (falling back to email). If you can pass a stable uid or email, do.

When it's quiet

No interviews arriving means the link isn't reaching people — not that people have nothing to say. Check the link's state and where you've shared it.

From your agent

• list_study_source_items — a study's interviews with status, quality, participant, and evidence counts.
• get_evidence — the verbatim evidence one interview produced (pass sourceItemIds).