Skip to main content
Executions are running instances of programs. When you launch a program, you create an execution that processes the audience, places calls, and tracks progress.

​
Understanding executions

Think of the relationship this way:
  • Program = Recipe (the instructions)
  • Execution = Cooking session (actually doing it)
You can run the same program multiple times, creating multiple executions. Each execution is independent—it has its own progress, status, and timing.

​
Execution lifecycle

Executions move through these states: 
scheduled ──▶ running ──▶ completed
                │
                ├──▶ paused ──▶ running (resumed)
                │
                └──▶ cancelled

running ──▶ stopped (when stopAt is reached)
StatusDescription
scheduledWaiting for startAt time
runningActively processing contacts
pausedManually paused, can resume
completedAll contacts processed
stoppedReached stopAt, remaining contacts skipped
cancelledManually cancelled

​
Launching an execution

Create an execution by launching a program: 
curl -X POST https://api.gomobile.ma/api/programs/PROGRAM_ID/launch \
  -H "x-api-key: YOUR_API_KEY"
Response: 
{
  "executionId": "770e8400-e29b-41d4-a716-446655440003"
}

​
Monitoring progress

Check execution status and progress: 
curl -X GET https://api.gomobile.ma/api/program-executions/EXECUTION_ID \
  -H "x-api-key: YOUR_API_KEY"
Response: 
{
  "id": "770e8400-e29b-41d4-a716-446655440003",
  "programId": "program-uuid",
  "status": "running",
  "totalContacts": 1500,
  "contactsCompleted": 750,
  "contactsFailed": 45,
  "contactsPending": 680,
  "contactsInProgress": 25,
  "scheduledStartAt": "2025-01-20T09:00:00.000Z",
  "scheduledStopAt": "2025-01-20T18:00:00.000Z",
  "actualStartAt": "2025-01-20T09:00:05.000Z",
  "createdAt": "2025-01-20T08:55:00.000Z",
  "updatedAt": "2025-01-20T12:30:00.000Z"
}

​
Progress counters

Understanding what each counter means:
CounterDescription
totalContactsAudience size at launch (snapshot)
contactsCompletedSuccessfully reached (answered, completed flow)
contactsFailedExhausted all retries
contactsPendingWaiting to be called (includes retry queue)
contactsInProgressCurrently being called or queued
These counters always sum to totalContacts: 
totalContacts = contactsCompleted + contactsFailed + contactsPending + contactsInProgress

​
Pausing and resuming

Pause a running execution: 
curl -X PATCH https://api.gomobile.ma/api/program-executions/EXECUTION_ID/pause \
  -H "x-api-key: YOUR_API_KEY"
When paused:
  • No new calls are initiated
  • Calls already in progress continue to completion
  • Retry schedules are preserved
Resume a paused execution: 
curl -X PATCH https://api.gomobile.ma/api/program-executions/EXECUTION_ID/resume \
  -H "x-api-key: YOUR_API_KEY"

​
Cancelling executions

Stop an execution permanently: 
curl -X DELETE https://api.gomobile.ma/api/program-executions/EXECUTION_ID \
  -H "x-api-key: YOUR_API_KEY"
When cancelled:
  • No new calls are initiated
  • Calls in progress continue to completion
  • Remaining pending contacts are marked as skipped
  • Cannot be resumed

​
Listing executions

View all executions for a program: 
curl -X GET https://api.gomobile.ma/api/programs/PROGRAM_ID/executions \
  -H "x-api-key: YOUR_API_KEY"
View all active executions across your organization: 
curl -X GET https://api.gomobile.ma/api/program-executions \
  -H "x-api-key: YOUR_API_KEY"
This returns only active executions (running, scheduled, paused).

​
Execution timing

Key timestamps:
TimestampDescription
scheduledStartAtWhen the execution should begin
scheduledStopAtWhen the execution should stop (optional)
actualStartAtWhen calls actually started
actualEndAtWhen the last call completed
If an execution reaches scheduledStopAt before completing all contacts, it enters stopped status and remaining contacts are not called.

​
Audience snapshots

When you launch an execution, Gomobile takes a snapshot of the audience. This means:
  • Contacts added to the audience after launch are NOT included
  • Contacts removed from the audience after launch ARE still called
  • This ensures predictable behavior during execution
To include new contacts, launch a new execution.

​
Multiple concurrent executions

You can’t run multiple executions of the same program simultaneously. If you try to launch while one is already running: 
{
  "error": "ExecutionAlreadyRunningError",
  "message": "Program already has a running execution"
}
Wait for the current execution to complete, or cancel it first.

​
Best practices

  • Monitor progress - Check counters periodically during large campaigns
  • Set stop times - Prevent executions from running indefinitely
  • Use pause wisely - Good for unexpected issues, not routine stops
  • Review failures - Understand why contacts failed before retrying
  • Clean up - Don’t leave paused executions hanging

Programs

The configuration that executions run.

Retry Strategies

How failures are retried.

Call Flows

What happens during calls.