Run and schedule a task

Run an implemented project task once, verify its result, then create a schedule for recurring execution. You need curl, jq, and uuidgen. Set an API credential with permission to create and read runs and manage schedules in the project. The example uses a task named daily-summary in support-assistant. Implement the task before running it. Creating task metadata alone does not implement its behavior.

1. Run the task once

Start the task with POST /runs. Replace <PROJECT_ID> with the project’s UUID:

run-task.sh

set -e

export PROJECT_ID="<PROJECT_ID>"
RUN_IDEMPOTENCY_KEY=$(uuidgen) || exit 1
export RUN_IDEMPOTENCY_KEY

jq -n --arg project "$PROJECT_ID" '{
  project_id: $project,
  title: "Daily summary",
  target: {type: "task", id: "daily-summary"}
}' > task-request.json

curl --fail-with-body https://api.veryfront.com/runs \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RUN_IDEMPOTENCY_KEY" \
  --data-binary @task-request.json > run.json

RUN_ID=$(jq -er '.id' run.json) || exit 1
export RUN_ID

Expect HTTP 202 and a run object with a top-level id. Acceptance means the run was created, not that the task finished successfully. Reuse the same idempotency key and request body when retrying this request. Use a new key for a separate run. A credential without read access receives only run_id and status; this walkthrough requires read access. The task runs against the main-branch deployment by default. If the task requires input, add its declared business input under input. The same input must be configured for scheduled executions.

2. Verify the one-off result

Poll GET /runs/{run_id} until the run completes or needs attention:

wait-for-task.sh

set -e

while true; do
  curl --fail-with-body "https://api.veryfront.com/runs/$RUN_ID" \
    -H "Authorization: Bearer $VERYFRONT_API_KEY" > result.json || exit 1
  status=$(jq -er '.status' result.json) || exit 1
  case "$status" in
    completed) jq '.output' result.json; break ;;
    failed|cancelled|waiting) jq '{status, error, control}' result.json; exit 1 ;;
    pending|running) sleep 2 ;;
    *) printf 'Unexpected run status: %s\n' "$status" >&2; exit 1 ;;
  esac
done

Confirm the output matches the task’s expected result before creating the schedule. If execution fails, inspect its events and error. A waiting run needs the input or resume condition recorded for it.

3. Create a recurring schedule

Schedule the task with POST /projects/{project_reference}/schedules:

schedule-task.sh

set -e

curl --fail-with-body https://api.veryfront.com/projects/support-assistant/schedules \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily summary",
    "target": {"kind":"task","id":"daily-summary"},
    "schedule": "0 8 * * *",
    "timezone": "Etc/UTC",
    "concurrency_policy": "Forbid"
  }' > schedule.json

jq '.schedule | {id, target, schedule, timezone, status}' schedule.json

Expect HTTP 201 and a schedule object. Confirm its status is active. This schedule runs at 08:00 UTC each day. Forbid prevents overlapping runs from this schedule.

Verify the result

Check the saved schedule’s target, timezone, and status. Each scheduled execution creates a separate run to inspect. Use a workflow when the implementation needs multiple coordinated steps. For a workflow run, set target.type to workflow and supply its definition ID and declared input. Schedule targets use kind, while direct run targets use type.

API references

Interface	Operations
REST	Create a run · Read a run · Create a schedule
GraphQL	Read a task · Discover schedules
MCP	Create a schedule · Read task definitions

Get started

APIs

REST API

GraphQL API

MCP API

Run and schedule a task

1. Run the task once

2. Verify the one-off result

3. Create a recurring schedule

Verify the result

API references

​1. Run the task once

​2. Verify the one-off result

​3. Create a recurring schedule

​Verify the result

​API references

1. Run the task once

2. Verify the one-off result

3. Create a recurring schedule

Verify the result

API references