Managing queuing¶

Info

Learn the concepts and fundamentals of queuing in the Explanation page.

Queuing lets you submit runs beyond your allowed maximum concurrency limits. Queues are maintained for each execution class and ordered by priority then age. Here are the controls you have for queuing:

Setting the priority, which must be a number between 1 (highest) and 9 (lowest). Default is 6.
Disabling queuing. Default behavior is to queue.

You can customize queuing behavior impacting runs by modifying the instance configuration, or directly when starting a run.

Managing queuing when running¶

You can configure queuing behavior when starting a run with the POST /v1/applications/{application_id}/runs endpoint in two ways:

Use it directly when starting a run with the queuing field of the configuration object in the request payload, or
Attach it to an instance with the queuing field of the configuration object when updating an instance, and use that instance when starting a run.

Here is an example where the queuing behavior is modified when starting a run.

BashOutput

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/drowsy-marmot/runs?instance_id=latest" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"name": "world", "radius": 6378, "distance": 147.6},
    "configuration": {"queuing": {"priority": 2}}
  }' \
  | jq '.'

{
  "run_id": "latest-n8cY9wEvg"
}

Once the run completes, retrieve its metadata using the GET /v1/applications/{application_id}/runs/{run_id}/metadata endpoint. The queuing_priority and queuing_disabled fields reflect the queuing configuration that was used for the run.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/drowsy-marmot/runs/latest-n8cY9wEvg/metadata" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '.'

{
  "id": "latest-n8cY9wEvg",
  "user_email": "sebastian@nextmv.io",
  "name": "",
  "description": "",
  "metadata": {
    "status": "succeeded",
    "status_v2": "succeeded",
    "created_at": "2026-07-29T14:28:07Z",
    "initiated_at": "2026-07-29T14:28:07.903507229Z",
    "duration": 7239,
    "execution_duration": 6149,
    "input_size": 52,
    "output_size": 25099,
    "error": "",
    "application_id": "drowsy-marmot",
    "application_instance_id": "latest",
    "application_version_id": "",
    "execution_class": "6c9500mb870s",
    "runtime": "python-3_11",
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "request_options": null,
      "options_summary": [
        {
          "name": "details",
          "value": "true",
          "source": "version"
        }
      ]
    },
    "queuing_priority": 2,
    "queuing_disabled": false,
    "metrics": {
      "message": "Hello, world",
      "value": 1.23
    }
  }
}

Let's say we have an instance identified as production. First, let's update it to disable queuing with the PUT /v1/applications/{application_id}/instances/{instance_id} endpoint. The endpoint expects the full instance payload, so the snippet below sends a GET request to fetch the current instance, uses jq to merge the configuration.queuing.disabled field into that response, and pipes the merged payload to a PUT request that updates the instance.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/drowsy-marmot/instances/production" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '. + {"configuration": {"queuing": {"disabled": true}}}' \
  | curl -s -X PUT "https://api.cloud.nextmv.io/v1/applications/drowsy-marmot/instances/production" \
      -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq '.'

{
  "name": "The main production instance",
  "id": "production",
  "application_id": "drowsy-marmot",
  "version_id": "version-dogowiwm",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": true
    }
  },
  "locked": false,
  "created_at": "2026-07-29T14:28:32.460772044Z",
  "updated_at": "2026-07-29T14:28:37.823041886Z"
}

We can now start a run using the production instance, and the attached queuing configuration will be used automatically.

BashOutput

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/drowsy-marmot/runs?instance_id=production" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"input": {"name": "world", "radius": 6378, "distance": 147.6}}' \
  | jq '.'

{
  "run_id": "production-ZohP9QPDR"
}

Retrieve the run's metadata again with the same GET /v1/applications/{application_id}/runs/{run_id}/metadata endpoint to confirm that queuing was disabled.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/drowsy-marmot/runs/production-ZohP9QPDR/metadata" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '.'

{
  "id": "production-ZohP9QPDR",
  "user_email": "sebastian@nextmv.io",
  "name": "",
  "description": "",
  "metadata": {
    "status": "succeeded",
    "status_v2": "succeeded",
    "created_at": "2026-07-29T14:28:42Z",
    "initiated_at": "2026-07-29T14:28:42.428863502Z",
    "duration": 5288,
    "execution_duration": 4334,
    "input_size": 52,
    "output_size": 25099,
    "error": "",
    "application_id": "drowsy-marmot",
    "application_instance_id": "production",
    "application_version_id": "version-dogowiwm",
    "execution_class": "6c9500mb870s",
    "runtime": "python-3_11",
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "request_options": null,
      "options_summary": [
        {
          "name": "details",
          "value": "true",
          "source": "version"
        }
      ]
    },
    "queuing_priority": 6,
    "queuing_disabled": true,
    "metrics": {
      "message": "Hello, world",
      "value": 1.23
    }
  }
}

Getting the queue of runs¶

Use the GET /v1/applications/{application_id}/runs endpoint to retrieve the list of runs that are currently queued. This endpoint is paginated, so the snippet below always uses pagination: it keeps requesting pages by passing the next_page_token value returned in each response as the pagetoken query parameter, until no token is returned. The endpoint does not support filtering by status directly, so jq is used to keep only the runs whose status_v2 is queued.

BashOutput

ITEMS="[]"
PAGE_TOKEN=""

while :; do
  RESPONSE=$(curl -s -G "https://api.cloud.nextmv.io/v1/applications/drowsy-marmot/runs" \
    -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
    --data-urlencode "limit=50" \
    --data-urlencode "pagetoken=${PAGE_TOKEN}")

  ITEMS=$(jq -n --argjson existing "$ITEMS" --argjson page "$(echo "$RESPONSE" | jq '.runs')" '$existing + $page')
  PAGE_TOKEN=$(echo "$RESPONSE" | jq -r '.next_page_token // empty')

  [ -z "$PAGE_TOKEN" ] && break
done

echo "$ITEMS" | jq '[.[] | select(.status_v2 == "queued")]'

[]