Skip to main content

​
Runs

A run is the execution of a work order. When you submit a work order, AgentGate creates a run to carry out the task. Runs track progress, status, and results.

​
What Is a Run

Each work order creates exactly one run. The run represents the entire execution lifecycle:
  • Workspace setup
  • AI agent execution
  • Iteration and verification cycles
  • Result generation

​
Run Lifecycle

Runs progress through these states:

​
Run States

StateDescriptionTerminal
pendingQueued, waiting to startNo
runningCurrently executingNo
succeededCompleted successfullyYes
failedCompleted with failureYes
cancelledStopped by user requestYes
Terminal states are final—the run will not change state again.

​
State Transitions

  • pending → running: Run starts execution
  • running → succeeded: All iterations passed verification
  • running → failed: Max iterations reached without success, or unrecoverable error
  • running → cancelled: User requested cancellation

​
Monitoring Runs

​
Polling

Retrieve run status by ID: 
curl https://agentgate.mynewapi.com/v1/runs/run_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
Polling creates API load. For production, use webhooks instead.
Configure webhooks to receive real-time notifications: 
{
  "url": "https://your-app.com/webhooks/agentgate",
  "events": ["run.completed", "run.failed"]
}
See Webhooks for setup instructions.

​
Run Results

When a run completes successfully, results include: 
{
  "id": "run_abc123",
  "workOrderId": "wo_xyz789",
  "status": "succeeded",
  "iterations": 3,
  "prUrl": "https://github.com/your-org/repo/pull/42",
  "timing": {
    "startedAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:35:00Z",
    "durationMs": 300000
  },
  "cost": {
    "credits": 150
  },
  "tenantContext": {
    "tenantId": "tenant_123",
    "tenantUserId": "user_456"
  }
}

​
Result Fields

FieldDescription
idRun identifier
workOrderIdAssociated work order
statusFinal status
iterationsNumber of iterations completed
prUrlPull request URL (if changes were made)
timingStart, end, and duration
costCredit cost of the run
tenantContextTenant info (if provided)

​
Run Timing

​
Duration

Run duration depends on:
  • Task complexity
  • Workspace size
  • Number of iterations needed
  • Verification level
Typical runs complete in 1-10 minutes.

​
Timeouts

Runs have a maximum execution time. If exceeded:
  • Run status becomes failed
  • Partial results may be available
  • Credits are charged for completed iterations

​
Cancelling Runs

Cancel a run that’s in progress: 
curl -X POST https://agentgate.mynewapi.com/v1/runs/run_abc123/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"
Only runs in pending or running state can be cancelled.
After cancellation:
  • Run status becomes cancelled
  • Any in-progress work stops
  • Credits are charged for completed iterations only
  • Webhook fires with run.cancelled event

​
Cost Information

Run costs are determined by:
  • Number of iterations
  • Complexity of verification
  • Workspace resources used
Check costs after completion in the run result or via the credits usage API.

​
Listing Runs

Retrieve all runs with filtering: 
curl "https://agentgate.mynewapi.com/v1/runs?status=succeeded&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

ParameterDescription
statusFilter by status
tenantUserIdFilter by tenant user
limitResults per page (max 100)
offsetPagination offset

Work Orders

Learn about creating work orders

Iterations

Understand the iteration and verification process