Help Center/ Live/ Cloud Live API Reference/ Stream Pull Management/ Querying Relay Tasks
Updated on 2026-01-07 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Querying Relay Tasks

Function

Query live stream pull and push tasks.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    live:stream:listPullTask

    Read

    -

    -

    -

    -

URI

GET /v1/{project_id}/pull/stream/task

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

region

No

String

Region where the task is located.

offset

No

Integer

Offset.

limit

No

Integer

Number of records per page.

task_id

No

String

Task ID.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token. This parameter is mandatory when token authentication is used. The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

task_infos

Array of LivePullTaskInfo objects

Stream pulling task list.

request_id

String

Request ID.

total

Integer

Number of tasks.
Table 5 LivePullTaskInfo

Parameter

Type

Description

task_id

String

Task ID.

status

String

Task status.

create_time

String

Creation time.

region

String

Region where the task is executed.

source_type

String

Source type for stream pull

PullLivePushLive: live-to-live

PullVodPushLive: VOD-to-live

source_urls

Array of strings

If source_type is set to PullLivePushLive, only one source URL can be specified.

Supported protocols: HTTP, HTTPS, RTMP, and RTMPS

domain

String

Ingest domain name.

app_name

String

Appliation name.

stream_name

String

Stream name.

push_args

String

Stream push parameter.

destination_url

String

Complete target URL.

If this parameter is specified, domain, app_name, and stream_name must be empty or not transferred.

start_time

String

Task start time.

end_time

String

Task end time.

  1. The end time must be later than the start time.

  2. The end time must be later than the current time.

  3. The interval between the end time and start time must be less than seven days.

callback_events

Array of strings

List of events to be called back. If this parameter is left blank, all events are called back.

TaskStart: task start callback

TaskExit: task stop callback

TaskAlarm: alarm event notification

callback_url

String

Callback address.

backup_source_type

String

Type of the standby source.

PullLivePushLive: livestreaming

backup_source_urls

Array of strings

If source_type is set to PullLivePushLive, only one source URL can be specified.

vod_loop_time

String

The default value is -1.

-1: infinite loop until the specified end time arrives; N: N rounds of playback based on the file list. Playback terminates when either the N rounds are completed or the specified end time is reached, whichever comes first.

If this parameter is not transferred or is left empty (""), the default value takes effect.

vod_start_video_index

Integer

Index of the file to be played. The value starts from 0, indicating the first file. The maximum value is len(source_urls) – 1.

vod_start_video_time

Integer

Second from which the specified file is played.

vod_refresh_type

String

File switching mode when a task is modified.

immediate_new_source: plays the content from the new source immediately.

continue_from_file_start: resumes streaming from the beginning of the last interrupted URL/file.

continue_from_break_point: resumes streaming from the exact breakpoint of the last interrupted URL/file (seamless continuation).

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error description.

request_id

String

Request ID.

Status code: 404

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error description.

request_id

String

Request ID.

Example Requests

GET https://{endpoint}/v1/{project_id}/pull/stream/task?region=cn-north-4&task_id=xxxxxx

Example Responses

Status code: 200

Successfully queried live stream pull and push tasks.

{
  "request_id" : "85968475-e92f-42db-a754-08e627b6d8dd",
  "total" : 1,
  "task_infos" : [ {
    "task_id" : "7864b3dc-e92f-42db-a754-08e627b6d8dd",
    "status" : "suspend",
    "create_time" : "2018-05-19T10:00:00Z",
    "region" : "cn-north-4",
    "source_type" : "PullLivePushLive",
    "source_urls" : [ "rtmp://play.example.huawei.com/live/stream1" ],
    "domain" : "publish.example.huawei.com",
    "app_name" : "live",
    "stream_name" : "test",
    "start_time" : "2018-05-19T18:00:00Z",
    "end_time" : "2018-05-19T21:00:00Z",
    "push_args" : "arg1=value1",
    "destination_url" : "",
    "callback_events" : [ "TaskStart", "TaskExit", "TaskAlarm" ],
    "callback_url" : "callback.example.com",
    "backup_source_type" : "PullLivePushLive",
    "backup_source_urls" : [ "rtmp://play.example.huawei.com/live/stream1_bak" ]
  } ]
}

Status code: 400

Failed to query the live stream pull and push task.

{
  "error_code" : "LIVE.100011001",
  "error_msg" : "Request Illegal",
  "request_id" : "85968475-e92f-42db-a754-08e627b6d8dd"
}

Status code: 404

Task does not exist.

{
  "error_code" : "LIVE.100011001",
  "error_msg" : "Request Illegal",
  "request_id" : "85968475-e92f-42db-a754-08e627b6d8dd"
}

Status Codes

Status Code

Description

200

Successfully queried live stream pull and push tasks.

400

Failed to query the live stream pull and push task.

404

Task does not exist.

Error Codes

See Error Codes.

Parent topic: Stream Pull Management