Skip to content
CXGear CXGear Docs

Running a job

A job is one execution of a published spinner across the rows in its data table (or the rows selected by the trigger). This page is the operator guide for Run now: what must be running, what you will see, and how long to wait.

Before you run

Section titled “Before you run”

Checklist:

  1. Data table has rows (verify with Show data)
  2. Metadata fields are set for columns the spinner needs
  3. Spinner is published (see Publishing)
  4. Channels / AI providers / vault secrets the steps need are configured
  5. The runtime service is up (see below)

Run now

Section titled “Run now”
  1. Open the project → Spinners.
  2. Find a published spinner (not a supporting child you never run by hand).
  3. Click Run now.
  4. Watch the status line on the list or open Jobs.
Screenshot needed
Spinners list with Run now on a published spinner and a status line.
Where: Project → Spinners
Save as: src/assets/screenshots/16-spinners-list.png

The API creates the job. The runtime executes each step for each row. If the runtime is down, the job may sit idle or never progress.

Runtime must be running

Section titled “Runtime must be running”

CXGear is split so the web app and API can stay light while heavy work runs in the runtime process.

PieceRole
Web / APIYou click Run now; job row is created
RuntimeWalks steps, calls AI, sends messages, writes outcomes

If jobs never move from queued / running with zero progress, ask your administrator to confirm the runtime service is online. Local developers usually run it alongside the API.

Progress messages

Section titled “Progress messages”

While a job runs you may see:

  • Counts of completed vs failed rows
  • Overall job status (running, completed, failed, partial)
  • Per-record messages in the pipeline journey (log lines, AI errors, channel results)

On Jobs:

  • Left: runs (spinner name, progress, status, duration)
  • Right: records for the selected run (paginated)
  • Use Refresh after a run finishes if the list has not updated yet
Screenshot needed
Jobs page with a running or completed job and records pane.
Where: Project → Jobs
Save as: src/assets/screenshots/08-jobs-page.png

Timing — especially AI

Section titled “Timing — especially AI”

Simple steps (log, tag) finish quickly. AI agent steps call an external model and can take up to about two minutes per record, depending on provider load and prompt size.

Plan expectations:

Pipeline styleWhat to expect
Log + tag onlySeconds to a short minute for small tables
AI draft + WhatsAppLonger; AI dominates wall time
Thousands of rows with AIMinutes to hours — watch Jobs progress, do not re-click Run now repeatedly

Do not assume the UI is stuck because one AI step is slow. Open the journey for a single record to see which step is active or failed.

Other ways jobs start

Section titled “Other ways jobs start”

Run now is the manual path. Jobs also start from:

  • Schedules / triggers configured on the spinner
  • API keys with trigger permission (CRM events)

Those paths still require a published definition and a healthy runtime. See Triggers.

Success looks like

Section titled “Success looks like”
  • Job status completed (or partial failures with clear errors on failed rows)
  • Records shows metadata plus outcomes for processed contacts
  • Journey shows each step’s message when you debug
  • Duration on the job matches the work (AI-heavy runs take longer)

Common problems

Section titled “Common problems”
SymptomLikely causeWhat to do
Job never movesRuntime not runningStart / restart runtime
Old behaviorSpinner not republished after editsPublish again
Plan limit toastMonthly jobs or records exceededSee Plan limits
AI step errorsBad model id, missing provider, vault secretCheck Integrations and journey error text
Empty RecordsJob failed early or no rowsCheck Jobs status and data table

Next

Section titled “Next”