Event types
CXGear records events as work moves through the system. You do not need to memorize every internal name. This page explains the families of events at a high level — enough to read a pipeline journey, talk to support, or design an integration without drowning in detail.
Why events exist
Section titled “Why events exist”Events answer:
- What started?
- What finished?
- What failed?
- How long did it take?
They power Jobs progress, Records status, and the pipeline journey timeline. Operators usually see summaries; builders see step events when debugging.
Three layers
Section titled “Three layers”Think in three layers, from wide to narrow:
Job events → one spinner run (many contacts)Record events → one contact inside that runStep events → one processor step for that contact| Layer | You care when… |
|---|---|
| Job | Is the campaign run healthy? |
| Record | What happened to this person? |
| Step | Which part of the pipeline failed or misbehaved? |
Job-level events
Section titled “Job-level events”A job is one execution of a published spinner.
Typical job lifecycle ideas:
| Event idea | Meaning |
|---|---|
| Job created / queued | Run was accepted (UI Run now, schedule, or public trigger) |
| Job started | Runtime picked up the work |
| Job progress | Records completed / failed counts move |
| Job completed | Runtime finished the batch |
| Job failed | Run stopped with a job-level error |
Jobs also store started, ended, and duration for monitoring. See Monitoring jobs.
Job creation can be blocked before any event is written if the plan meter is full (PLAN_LIMIT).
Record-level events
Section titled “Record-level events”A record is one contact’s execution inside a job.
| Event idea | Meaning |
|---|---|
| Record started | This contact entered the pipeline |
| Record completed | Steps finished successfully enough to mark done |
| Record failed | A step error stopped this contact |
| Record waiting | Paused on an external or human step |
Records keep:
- Metadata payload — inputs that entered the pipeline
- Outcomes — operational results (disposition, AI text, message ids)
- Status / timing — for ops reporting
Internal debug noise is hidden from the main Records view. See Metadata vs pipeline output.
Step-level events (journey)
Section titled “Step-level events (journey)”Each spinner step (log, AI agent, WhatsApp, tag, function tool, …) emits journey events for that record.
| Event idea | Meaning |
|---|---|
| Step started | Processor began |
| Step completed | Processor finished with an outcome key (for example logged, ai_completed) |
| Step failed | Processor error (provider, validation, timeout) |
| Step message | Human-readable detail (log template text, console lines, error strings) |
The pipeline journey drawer is the UI for step events. Use it when debugging — not for every ops review. See When to use the journey.
Outcome keys vs events
Section titled “Outcome keys vs events”Steps often produce a short outcome key (what kind of result) plus optional message text. Records promote the most useful operational outcomes into the Outcomes panel; the journey keeps the full step trail.
Related product events (outside a spinner)
Section titled “Related product events (outside a spinner)”Not every important signal is a spinner step:
| Area | Examples |
|---|---|
| Auth / sessions | Login, logout, session replaced, password reset |
| Billing | Plan change, limit reached |
| Channels | OAuth connected, inbound webhook received |
| Dialler | Presence changes, call state (UI uses realtime streams for agents) |
Those matter for security and operations but are not shown as pipeline journey steps.
How to use this as an operator
Section titled “How to use this as an operator”- Check Live Ops for attention items.
- Open Jobs for run status and duration.
- Open Records for per-contact outcomes.
- Open Pipeline journey only when a record needs step-level explanation.
How to use this as a builder
Section titled “How to use this as a builder”- Add Log steps while testing so journey messages are readable.
- Read step failure messages before changing unrelated config.
- Remember finished jobs keep historical events — fix the spinner and run again.
Success looks like
Section titled “Success looks like”- You can explain a failure using job → record → step
- Ops stays on Records; debug uses journey events
- Support requests include job id, record, and step message text
Common problems
Section titled “Common problems”| Problem | Likely cause | What to do |
|---|---|---|
| No step events | Job never started or runtime down | Check Jobs and runtime |
| Journey empty on success | Steps emitted little message text | Add log steps while building |
| Outcome missing but steps ran | Step did not write an ops outcome | Adjust Tag / AI / channel steps |
| Looking for CSV columns in events | Only metadata enters the pipeline | Configure metadata fields |