Running Tasks

Tasks are executed by queuing executions. You can run them from the reArray UI or programmatically via the Integration API.

Manual runs (UI)

1. Open Tasks and select a task.
2. Click Run.
3. Choose the agent that should execute the run.
4. Fill in the params form if the task defines a params schema.
5. Confirm to queue the execution.

The execution appears in Executions with status queued, then running once an agent worker claims it.

Manual runs do not send webhook callbacks — use the API with callback_url for outbound notifications.

API runs

Queue executions with POST /api/v1/integrations/executions:

curl -X POST https://your-app.example.com/api/v1/integrations/executions \
  -H "Authorization: Bearer ra_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-0000-0000-000000000001",
    "task_id": "00000000-0000-0000-0000-000000000002",
    "params": { "orderId": "ORD-123" },
    "reference": "ORD-123",
    "metadata": { "source": "erp" },
    "callback_url": "https://api.example.com/hooks/rearray",
    "priority": 10
  }'

Required fields: agent_id, and either task_id or task_version_id.

See Executions API for the full endpoint reference.

Scheduling

Defer execution start with scheduled_at (ISO 8601 datetime):

{
  "agent_id": "...",
  "task_id": "...",
  "scheduled_at": "2026-06-15T09:00:00+00:00"
}

Scheduled executions remain pending until the scheduled time, then move to queued.

Priority

Set priority (-1000 to 1000) to influence queue ordering. Higher values are processed sooner when multiple executions compete for the same agent. Default is 0.

Idempotency

Pass an Idempotency-Key header to prevent duplicate runs from retried requests:

curl -X POST https://your-app.example.com/api/v1/integrations/executions \
  -H "Authorization: Bearer ra_live_your_key" \
  -H "Idempotency-Key: ord-123-create" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "...", "task_id": "...", "reference": "ORD-123" }'

If the same API key and idempotency key were used before, the API returns the original execution with idempotent_replay: true instead of creating a duplicate.

Validation without queuing

Use validate_only=true to validate params and permissions without creating an execution:

curl -X POST "https://your-app.example.com/api/v1/integrations/executions?validate_only=true" \
  -H "Authorization: Bearer ra_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "...", "task_id": "...", "params": { ... } }'

Returns would_create: true on success.

Aborting and cancelling

From the UI

Open an execution in pending, queued, or running status and click Abort. The execution moves to aborted.

From the API

curl -X POST https://your-app.example.com/api/v1/integrations/executions/{id}/cancel \
  -H "Authorization: Bearer ra_live_your_key"

Cancellable statuses: pending, queued, running.

Choosing task versions

By default, executions use the task's latest version. Target a specific version:

{
  "agent_id": "...",
  "task_id": "...",
  "version": "3"
}

Or pass the version UUID directly:

{
  "agent_id": "...",
  "task_version_id": "00000000-0000-0000-0000-000000000003"
}

Use version: "current" explicitly to pin to the latest published version at queue time.