DescribeLivePullToPush - ApsaraVideo Live - Alibaba Cloud Documentation Center

Call the DescribeLivePullToPush operation to query pull-to-push tasks.

Operation description

Call this operation to query pull-to-push tasks.
You can query the configuration and status of a task by its ID.

QPS limits

A single user can perform a maximum of 10 queries per second (QPS) on this operation. If you exceed this limit, your API calls are throttled. This may affect your business. Plan your API calls accordingly.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

live:DescribeLivePullToPush

get

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	No	The region ID.	cn-shanghai
TaskId	string	Yes	The task ID.	fd245384-4067-4f91-9d75-9666a6bc****
Region	string	Yes	The region where the task runs. Valid values: ap-southeast-1 (Singapore) ap-southeast-5 (Indonesia) cn-beijing (Beijing) cn-shanghai (Shanghai)	cn-shanghai

Response elements

Element	Type	Description	Example
	object	Response parameters
RequestId	string	The request ID.	a05e6b15-15af-405b-a4a2-0152245d****
RetCode	integer	The return code. Note A value of 0 indicates that the request was successful. For other values, see the error codes in this topic.	0
Description	string	The error description.	OK
TaskId	string	The ID of the created task.	fb0d4ac7-c7e3-4978-9743-0bf2f6e8****
TaskStatus	integer	The current status of the task: 0: Not started. The scheduled start time has not been reached. 1: Running. Stream pulling and ingest are normal. 2: Abnormal 3: Stopped. Stream pulling or ingest is abnormal, or the task was stopped by an API call. -1: Exited	0
TaskInvalidReason	string	The reason why the task stopped: PullStreamFailed: An error occurred when pulling the source stream. The system is retrying. PushStreamFailed: An error occurred when ingesting the destination stream. The system is retrying. UnknownError: An unknown error occurred. Note This parameter is returned only when the task is stopped.	PullStreamFailed
TaskExitTime	integer	The time when the task exited. This is a Unix timestamp in seconds. Note This parameter is returned only if the task has exited.	1726354625
TaskExitReason	string	The reason why the task exited: TriggerByUser: The task was stopped by a user. OverEndTime: The scheduled end time was reached. Note This parameter is returned only if the task has exited.	TriggerByUser
CurrentOffset	integer	The current video playback offset.	0
CurrentFileIndex	integer	The current playlist sequence offset.	0
TaskInfo	object	The task information.
TaskId	string	The task ID.	fd245384-4067-4f91-9d75-9666a6bc9****
TaskName	string	The task name.	test
StartTime	string	The start time of the task. The time is in the yyyy-MM-ddTHH:mm:ssZ format and is displayed in UTC.	2024-08-26T10:30:00Z
EndTime	string	The end time of the task. The time is in the yyyy-MM-ddTHH:mm:ssZ format and is displayed in UTC.	2024-08-27T14:30:00Z
SourceType	string	The type of the source stream. Valid values: live: a live stream. vod: a VOD resource. url: a third-party video file resource.	vod
SourceProtocol	string	The protocol of the source stream.	RTMP
SourceUrls	array	The URLs of the source streams.	rtmp://pulltest.****.aliyunlive.com/pulltest493/pulltest-w434
	string	A URL of a source stream.	rtmp://pulltest.****.aliyunlive.com/pulltest493/pulltest-w434
DstUrl	string	The destination URL for stream ingest.	rtmp://pushtest.********.aliyunlive.com/pulltest493/pulltest-w434
CallbackURL	string	The HTTP webhook URL.	https://callback*****.com
Offset	integer	The start offset of the video file. Unit: seconds. The value must be greater than 0. Note This parameter specifies the time offset from the first frame at which to start playback. This parameter is valid only for VOD resources or video files.	0
FileIndex	integer	The file index. Playback starts from the specified file in the list of source URLs.	0
RetryCount	integer	The number of retries.	3
RetryInterval	integer	The retry interval. Unit: seconds.	60
RepeatNumber	integer	The number of times to repeat playback after the source ends. Valid values: 0 (default): Playback does not repeat. -1: The stream loops indefinitely. Other positive integers: The number of times to repeat playback. Note This parameter is valid only for VOD or third-party video sources.	0

Examples

Success response

JSON format

{
  "RequestId": "a05e6b15-15af-405b-a4a2-0152245d****",
  "RetCode": 0,
  "Description": "OK",
  "TaskId": "fb0d4ac7-c7e3-4978-9743-0bf2f6e8****",
  "TaskStatus": 0,
  "TaskInvalidReason": "PullStreamFailed",
  "TaskExitTime": 1726354625,
  "TaskExitReason": "TriggerByUser",
  "CurrentOffset": 0,
  "CurrentFileIndex": 0,
  "TaskInfo": {
    "TaskId": "fd245384-4067-4f91-9d75-9666a6bc9****",
    "TaskName": "test",
    "StartTime": "2024-08-26T10:30:00Z",
    "EndTime": "2024-08-27T14:30:00Z",
    "SourceType": "vod",
    "SourceProtocol": "RTMP",
    "SourceUrls": [
      "rtmp://pulltest.****.aliyunlive.com/pulltest493/pulltest-w434"
    ],
    "DstUrl": "rtmp://pushtest.********.aliyunlive.com/pulltest493/pulltest-w434",
    "CallbackURL": "https://callback*****.com",
    "Offset": 0,
    "FileIndex": 0,
    "RetryCount": 3,
    "RetryInterval": 60,
    "RepeatNumber": 0
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidParameter	%s.	Parameter error
400	CodeInvalidAliUid	This aliuid does not have a live domain name.	This aluid does not have a live domain name.
500	InternalError	%s.	error on the live liveapi server.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.