Skip to main content
  • Core Products
  • Add-Ons
  • Extensions Marketplace

    Query streaming information

    This method queries an ongoing push based on SID.

    Prototype​

    • Method: GET
    • Endpoint: https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/online-streams/:sid

    Request parameters​

    Authentication

    • HTTP Basic Authentication

      Every time you send an HTTP request, you must pass in a credential in the Authorization field in the HTTP request header. See RESTful Authentication on how to generate it.

      Basic authentication is a simple authentication scheme built into the HTTP protocol. To use it, send your HTTP requests with an Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.

      Example: Authorization: Basic ZGVtbzpwQDU1dzByZA==

    • HTTP HMAC Authentication

      Every time you send an HTTP request, you must pass in an API key in the Authorization field in the HTTP request header. See RESTful Authentication on how to generate it.

      Example: Authorization: 123

    Path parameters

    ParameterData typeRequired/OptionalDescription
    appIdStringRequiredThe app ID provided by Agora to each developer. After creating a project in Agora Console, you can get an app ID. The app ID is a unique identifier for a project.
    regionStringRequiredCreate an area for pushing the streaming key. Agora supports creation of stream keys by region. Currently, the following regions are supported:
    • na: North America
    • eu: Europe
    • ap: Asia, except mainland China
    • cn: Mainland China
    Important
    Make sure that:
    • The region value is the same as for the input source stream.
    • The domain names for setting the region parameter and streaming are the same.
    • The region value is in the lowercase.
    sidStringRequiredThe streaming session ID is the unique identifier for each initiated streaming task. It can be obtained by querying the streaming list or receiving the payload of the message notification callback.

    Headers

    HeaderData typeDescription
    X-Request-IDStringThe UUID (Universally Unique Identifier) of the request. After passing in this field, the Agora server will return this field in the response header. It is recommended to assign X-Request-ID a value. If no value is assigned, the Agora server will automatically generate a UUID and pass it in.

    Request example​


    _5
    curl --request GET \
    _5
    --url https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams/sid \
    _5
    --header 'Accept: application/json' \
    _5
    --header 'Authorization: Basic 123' \
    _5
    --header 'X-Request-ID: '

    Response parameters​

    Headers

    HeaderData typeDescription
    X-Request-IDStringThe UUID (Universally Unique Identifier) of the request. The value is in its X-Request-ID header. If a request error occurs, print the value in the log to troubleshoot the problem. A 401 (Unauthorized) response status code means that there is no such field in the response header.

    Response body

    For details about possible response status codes, see Response status codes.

    If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure.

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    statusStringThe status of this request. success means the request succeeds.
    dataObjectIncludes the following fields:
    • sid: String, a streaming session ID. A unique sid will be generated for each stream.
    • channel: String. The name of the Agora channel associated with the streaming key.
    • uid: String, the user UID in the Agora channel associated with the streaming key.
    • url: String, the push address in the $domain/live/$streamkey format.
    • status: String, the flow status. Possible values are the following:
      • "Started": Connection has been established, waiting to stream audio and video.
        • "Running": Is being streamed.
    beginAtStringStreaming start time in the "2024-01-01 01:01:01.001" format.
    bitrateIntegerThe source stream bitrate (audio + video) of the pushed stream, in Kbps.
    videoObjectVideo stream parameters, returned only if the status is "Running":
    • width: Number, video width in pixels.
    • height: Number, video height in pixels.
    • fps: Video frame rate in frames per second.
    audioObjectAudio stream parameters, returned only if the status is "Running":
    • channels: Number, the number of audio channels.
    • sampleRate: Number, audio sampling rate in Hz.

    Response example​

    The following is a response example for a successful request:


    _23
    {
    _23
    "status" : "string" ,
    _23
    "data" : [
    _23
    {
    _23
    "sid" : "string" ,
    _23
    "channel" : "string" ,
    _23
    "uid" : "string" ,
    _23
    "url" : "string" ,
    _23
    "status" : "string" ,
    _23
    "beginAt" : "string" ,
    _23
    "bitrate" : 0 ,
    _23
    "video" : {
    _23
    "width" : 0 ,
    _23
    "height" : 0 ,
    _23
    "fps" : 0
    _23
    } ,
    _23
    "audio" : {
    _23
    "channels" : 0 ,
    _23
    "sampleRate" : 0
    _23
    }
    _23
    }
    _23
    ]
    _23
    }

    Info

    To explore the RESTful API parameters, obtain sample code in various client languages, or test Media Gateway requests, refer to the Postman API reference.

    vundefined