4.3.9. TaskStatus

Description

The method returns the status of a task by its task_ids and allows you to track the current stage of verification task.

Request

{
  "user_id":(number),
  "methods":[
    {
      "method":"TaskStatus",
      "params":{
        "project_id":(number),
        "task_ids":' id1 | [id1,id2] | "*" ',
        "detailed_test_results":(boolean),
        "restart_chain":(string)
      }
    }
  ]
}

where:

• user_id — an integer value, a user identifier;

• project_id — an integer value, a user project identifier;

• task_ids — task identifiers, the field can be specified in one of the following formats:

  • id1 — an integer value, a task identifier,

  • [id1,id2] — an array of integer values, task identifiers,

  • "*" — a string, the “asterisk” symbol, request for all running tasks, as well as tasks in the queue.

• detailed_test_results (optional field) — a logical type, controls the level of detail of test_results field:

  • true — the method returns the results for each group of tests separately, as well as the total test result. List of group of test: file_summary, container_validation, video_parameters, audio_parameters, video_quality and audio_quality.

  • false (by default) — the method returns only total test result.

• restart_chain (optional field) — a string, controls the display of statuses for a chain of restarted tasks. Available values: first, last, exact, all (by default).

  About the restart chain

  Tasks with the same initial_task_id form a chain-group of restarted tasks in the reply. These are tasks with the Stalled status, that were automatically sent for re-checking. The project settings specify an automatic restart scenario for tasks with the Stalled status. By default, task restart is enabled, and the number of restarts is 3. The scenario can be changed in the project settings (see the Restart tasks settings) or using the ProjectSettingsChange method. Each restart creates a new task with a new task_id, but the initial_task_id value for all tasks in the chain is the same and equals the task_id of the original task.

  Thus, initial_task_id allows you to:

  • find all restarts related to a single original task;

  • track whether the task was ultimately completed (successfully or not) after all restart attempts.

  The key restart_chain determines which task statuses from the chain should be returned:

  1. first — status of only the original (very first) task in the chain. Information about restarts is not included.

  2. last — status of only the last task in the chain. Intermediate restarts are not included.

  3. exact — status of only the specific task_id provided in the request. Useful when you need to check the status of a particular task (e.g., an intermediate restart).

  4. all (by default) — statuses of all tasks in the restart chain (the original task and all its restarts).

Reply

{
  "reply":[
    {
      "method":"TaskStatus",
      "result":[
        {
          "task_id":(number),
          "uri":(string),
          "name":(string),
          "status":(string),
          "initial_task_id":(number),
          "progress":(number),
          "test_results":{
            "ok":(number),
            "warning":(number),
            "error":(number),
            "fatal":(number),
            "result":(string)
          },
          "task_page":(string),
          "requested_task_ids":[]
        }
      ],
      "errors":[(string)]
    }
  ]
}

where:

• task_id — an integer value, a user identifier;

• uri — a string, location of media file that’s being validated;

• name — a string, media file validation task’s name;

• status — a string, status, indicates the stage of the task. List of statuses:

  • Scheduled — task is created and queued for launch. Next, the load balancer will evenly distribute the tasks from queue among the available project’s probes according to priority, then the status will change to one of the below-mentioned;

  • Explore — task sent to probe for look-ahead analysis;

  • Running — task launched;

  • Completed — task completed;

  • Rejected — task launch rejected. To learn why that happened, see the Dashboard page → Incomplete tasks block. Possible reasons:

    • Media file’s total duration is 0 seconds or probe failed to define duration,

    • Media file not found via the specified URI,

    • Media file fails to follow the test template’s compliance conditions. Inside the test templates’ settings, the Stop if condition not met option is enabled for Container Format, Video Format, or Audio Format tests. It can be disabled there,

    • Media file format not supported;

    • Access to media file validation is temporarily suspended when the license balance fully runs out or its remaining balance is less than the duration of the file submitted for validation. To learn more about the principle of using the license balance, see here.

  • Canceled — task stopped. Possible scenarios:

    • the task was stopped by the user in the web interface or using the TaskStop method. The reason will be indicated in the Dashboard → Incomplete tasks block,

    • The task was stopped by the load balancer because it was replaced by a task with the Immediate priority. For more details on load balancer operation and priority descriptions, see the Dashboard page.

  • Stalled — task stopped incorrectly and placed in the Dashboard → Incomplete tasks block. Server stopped obtaining analysis data, but the stop task command was never received. Normally this has to do with the server losing connection with the probe, or with the probe finishing its work incorrectly. In this case, the task will be restarted 3 times (by default). Automatic task restart scenario can be configured in Project settings ➝ Restart Stalled tasks tab.

• initial_task_id — an integer value, the identifier of a task group within a restart chain. For any task in the group including the first one initial_task_id value is equal to the task_id value of the first task itself. If there were no restarts, the initial_task_id value matches the task_id value of the task itself.

• progress — an integer value, represents the progress of the task as a percentage. Progress is displayed for tasks with Running and Completed statuses;

• test_results — depending on the detailed_test_results value in the request, the method’s response includes:

  • ok — an integer value, the number of tests without errors,

  • warning — an integer value, the number of tests with the warning severity level in which at least one error has been detected,

  • error — an integer value, the number of tests with the error severity level in which at least one error has been detected,

  • fatal — an integer value,the number of tests with the fatal severity level in which at least one error has been detected,

  or a separate result for each group of tests:

  • file_summary,

  • container_validation,

  • video_parameters,

  • audio_parameters,

  • video_quality,

  • audio_quality,

  • total (total test result).

• result — a string, task result:

  • Passed — a string, all template tests were passed successfully. Media file fully meets the requirements,

  • Warning — a string, the task is completed, but the report contains errors with the Warning severity level,

  • Failed — a string, the task is completed, but the report contains errors with the Error and (or) Fatal severity level.

• task_page — a string, task web page URL;

• requested_task_ids — array of integer values, целых чисел, identifiers of the requested tasks;

• errors — array of strings, returns a list of errors.

Example

Request by the cURL utility

#1. A simple request for the status of a single task
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskStatus","params":{"project_id":2,"task_ids":[2213]}}]}'

#2. An example with additional field detailed_test_results = true
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskStatus","params":{"project_id":2,"task_ids":[2213],"detailed_test_results":true}}]}'

#3. Request for status for three tasks with task_id 2213, 2222, 2288. The third task has a non-existent value in the task_ids field.
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskStatus","params":{"project_id":2,"task_ids":[2213,2222,2288]}}]}'

#4. Request for status for three tasks with task_id 2213, 2222, 2247. The third task received the status Stalled and was automatically restarted twice.
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskStatus","params":{"project_id":2,"task_ids":[2213,2222,2247],"detailed_test_results":false,"restart_chain":"all"}}]}'

#5. Request for the status of task with task_id 2247 with the status Stalled and parameter restart_chain = all.
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskStatus","params":{"project_id":2,"task_ids":[2247],"detailed_test_results":false,"restart_chain":"all"}}]}'

#6. Request for the status of task with task_id 2247 with the status Stalled and parameter restart_chain = first.
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskStatus","params":{"project_id":2,"task_ids":[2247],"detailed_test_results":false,"restart_chain":"first"}}]}'

#7. Request for the status of task with task_id 2247 with the status Stalled and parameter restart_chain = last.
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskStatus","params":{"project_id":2,"task_ids":[2247],"detailed_test_results":false,"restart_chain":"last"}}]}'

#8. Request for the status of task with task_id 2248 with the status Stalled and parameter restart_chain = exact.
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskStatus","params":{"project_id":2,"task_ids":[2248],"detailed_test_results":false,"restart_chain":"exact"}}]}'

Reply to request from example #1

{
  "reply": [
    {
      "method": "TaskStatus",
      "result": [
        {
          "task_id": 2213,
          "uri": "file:///mnt/VoD_storage/sample1.mp4",
          "name": "",
          "status": "Completed",
          "initial_task_id": 2213,
          "progress": 100,
          "test_results": {
            "ok": 36,
            "warning": 1,
            "error": 12,
            "result": "Failed"
          },
          "task_page": "http://172.16.1.41/projects/2/apps/17/tasks/2213",
          "requested_task_ids": [2213]
        }
      ]
    }
  ]
}

Reply to request from example #2

{
  "reply": [
    {
      "method": "TaskStatus",
      "result": [
        {
          "task_id": 2213,
          "uri": "file:///mnt/VoD_storage/sample1.mp4",
          "name": "",
          "status": "Completed",
          "initial_task_id": 2213,
          "progress": 100,
          "test_results": {
            "file_summary": {
              "ok": 9,
              "warning": 1,
              "error": 2
            },
            "container_validation": {
              "ok": 5,
              "error": 1
            },
            "video_parameters": {
              "ok": 16,
              "error": 6
            },
            "audio_parameters": {
              "ok": 3,
              "error": 2
            },
            "video_quality": {
              "ok": 1,
              "error": 1
            },
            "audio_quality": {
              "ok": 2
            },
            "total": {
              "ok": 36,
              "warning": 1,
              "error": 12
            },
            "result": "Failed"
          },
          "task_page": "http://172.16.1.41/projects/2/apps/17/tasks/2213",
          "requested_task_ids": [
            2213
          ]
        }
      ]
    }
  ]
}

Reply to request from example #3

{
  "reply": [
    {
      "method": "TaskStatus",
      "result": [
        {
          "task_id": 2222,
          "uri": "file:///mnt/VoD_storage/sample2.mp4",
          "name": "Test2",
          "status": "Completed",
          "progress": 100,
          "test_results": {
            "ok": 37,
            "warning": 1,
            "error": 8,
            "fatal": 1,
            "result": "Failed"
          },
          "task_page": "http://172.16.1.41/projects/2/apps/17/tasks/2222"
        },
        {
          "task_id": 2213,
          "uri": "file:///mnt/VoD_storage/sample1.mp4",
          "name": "",
          "status": "Completed",
          "progress": 100,
          "test_results": {
            "ok": 36,
            "warning": 1,
            "error": 12,
            "result": "Failed"
          },
          "task_page": "http://172.16.1.41/projects/2/apps/17/tasks/2213"
        },
      ],
      "errors": [
        "Requested task IDs do not exist: [2288]"
      ]
    }
  ]
}

Reply to request from example #4

{
  "reply": [
    {
      "method": "TaskStatus",
      "result": [
        {
          "task_id": 2213,
          "uri": "file:///mnt/VoD_storage/sample1.mp4",
          "name": "",
          "status": "Completed",
          "initial_task_id": 2213,
          "progress": 100,
          "test_results": {
            "error": 12,
            "ok": 36,
            "warning": 1,
            "result": "Failed"
          },
          "task_page": "http://172.16.1.41/projects/2/apps/17/tasks/2213",
          "requested_task_ids": [
            2213
          ]
        },
        {
          "task_id": 2222,
          "uri": "file:///mnt/VoD_storage/sample2.mp4",
          "name": "",
          "status": "Completed",
          "initial_task_id": 2222,
          "progress": 100,
          "test_results": {
            "ok": 37,
            "error": 8,
            "warning": 1,
            "fatal": 1,
            "result": "Failed"
          },
          "task_page": "http://172.16.1.41/projects/2/apps/17/tasks/2222",
          "requested_task_ids": [
            2222
          ]
        },
        {
          "task_id": 2249,
          "uri": "file:///mnt/VoD_storage/sample3.mp4",
          "name": "Test Stalled",
          "status": "Completed",
          "initial_task_id": 2247,
          "progress": 100,
          "test_results": {
            "error": 24,
            "ok": 28,
            "warning": 1,
            "fatal": 2,
            "result": "Failed"
          },
          "task_page": "http://172.16.1.41/projects/2/apps/1/tasks/2249",
          "requested_task_ids": [
            2247
          ]
        },
        {
          "task_id": 2247,
          "uri": "file:///mnt/VoD_storage/sample3.mp4",
          "name": "Test Stalled",
          "status": "Stalled",
          "initial_task_id": 2247,
          "requested_task_ids": [
            2247
          ]
        },
        {
          "task_id": 2248,
          "uri": "file:///mnt/VoD_storage/sample3.mp4",
          "name": "Test Stalled",
          "status": "Stalled",
          "initial_task_id": 2247,
          "requested_task_ids": [
            2247
          ]
        }
      ],
    }
  ]
}

Reply to request from example #5

{
  "reply": [
    {
      "method": "TaskStatus",
      "result": [
        {
          "task_id": 2247,
          "uri": "file:///mnt/VoD_storage/sample3.mp4",
          "name": "Test Stalled",
          "status": "Stalled",
          "initial_task_id": 2247,
          "requested_task_ids": [
            2247
          ]
        },
        {
          "task_id": 2248,
          "uri": "file:///mnt/VoD_storage/sample3.mp4",
          "name": "Test Stalled",
          "status": "Stalled",
          "initial_task_id": 2247,
          "requested_task_ids": [
            2247
          ]
        },
        {
          "task_id": 2249,
          "uri": "file:///mnt/VoD_storage/sample3.mp4",
          "name": "Test Stalled",
          "status": "Completed",
          "initial_task_id": 2247,
          "progress": 100,
          "test_results": {
            "error": 24,
            "ok": 28,
            "warning": 1,
            "fatal": 2,
            "result": "Failed"
          },
          "task_page": "http://172.16.1.41/projects/2/apps/1/tasks/2249",
          "requested_task_ids": [
            2247
          ]
        }
      ]
    }
  ]
}

Reply to request from example #6

{
  "reply": [
    {
      "method": "TaskStatus",
      "result": [
        {
          "task_id": 2247,
          "uri": "file:///mnt/VoD_storage/sample3.mp4",
          "name": "Test Stalled",
          "status": "Stalled",
          "initial_task_id": 2247,
          "requested_task_ids": [
            2247
          ]
        }
      ]
    }
  ]
}

Reply to request from example #7

{
  "reply": [
    {
      "method": "TaskStatus",
      "result": [
        {
          "task_id": 2249,
          "uri": "file:///mnt/VoD_storage/sample3.mp4",
          "name": "Test Stalled",
          "status": "Completed",
          "initial_task_id": 2247,
          "progress": 100,
          "test_results": {
            "error": 24,
            "ok": 28,
            "warning": 1,
            "fatal": 2,
            "result": "Failed"
          },
          "task_page": "http://172.16.1.41/projects/2/apps/1/tasks/2249",
          "requested_task_ids": [
            2247
          ]
        }
      ]
    }
  ]
}

Reply to request from example #8

{
  "reply": [
    {
      "method": "TaskStatus",
      "result": [
        {
          "task_id": 2248,
          "uri": "file:///mnt/VoD_storage/sample3.mp4",
          "name": "Test Stalled",
          "status": "Stalled",
          "initial_task_id": 2247,
          "requested_task_ids": [
            2248
          ]
        }
      ]
    }
  ]
}