Platform DocsPlayers DocsRelease Notes
System StatusSubmit a CaseDashboard LoginContact Sales

Listing Media

The GET https://api.jwplayer.com/v2/sites/{site_id}/media/ API call enables you to retrieve a list of the media associated with a property. For each media item, the Platform Management API returns information that pertains to the creation, type, and metadata of the media.


List Media

Use the following steps to display the media associated with a property:

  1. Add your secret to the Authorization header of your API request to authenticate the request.
  2. Make a GET https://api.jwplayer.com/v2/sites/{site_id}/media/ call. Be sure to replace {site_id} with a valid site ID value.
curl -X GET 'https://api.jwplayer.com/v2/sites/{site_id}/media/'
     -H 'Authorization: Bearer {v2_api_secret}'

import requests

site_id = "my_site_id"
v2_api_secret = "my_api_secret"

url = f"https://api.jwplayer.com/v2/sites/{site_id}/media/"

payload={}
headers = {
  "Authorization": f"Bearer {v2_api_secret}"
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

🚧

The API returns an upper limit of 10,000 media per search query. Regardless of pagination, only the first 10,000 results based on the sorting used may be retrieved. For listing media in a large library, see List all media items in a large library.

By default, the API displays 10 records per page.


Use cases

Retrieving a list of media from a property can be the only step or one step within a larger workflow. The following use cases illustrate how the GET https://api.jwplayer.com/v2/sites/{site_id}/media call can solve business problems.


Updating media metadata in bulk

User story: Levi is a video editor for Info Today. He has been uploading his entertainment culture videos without categorizing them. Info Today has decided that all Levi's videos should be categorized as Pop Culture. Info Today has a library of 400 videos.

Objective: For a property with a total of 400 videos, identify all Levi's videos. Then, update the category property of each video.



  1. Make a GET https://api.jwplayer.com/v2/sites/{site_id}/media/?q=author:levi&page_length=400 call.

    The q query (q=author:levi) restricts the list to only media items authored by Levi.

    In a property that contains a total of 400 videos, the page_length query parameter (page_length=400) ensures that the Platform Management API displays all the media items authored by Levi in a single response. By default, the Platform Management API returns 10 items per page of results.
curl -X GET 'https://api.jwplayer.com/v2/sites/{site_id}/media/?q=author:levi&page_length=400'
     -H 'Authorization: Bearer {v2_api_secret}'

import requests

site_id = "my_site_id"
v2_api_secret = "my_api_secret"

url = f"https://api.jwplayer.com/v2/sites/{site_id}/media/?q=author:levi&page_length=400"

payload={}
headers = {
  "Authorization": f"Bearer {v2_api_secret}"
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.json())

{
    "media": [{
            "created": "2021-07-21T14:33:18+00:00",
            "duration": 14.744999885559082,
            "error_message": null,
            "external_id": null,
            "hosting_type": "hosted",
            "id": "1234abcd",
            "last_modified": "2021-08-29T19:47:18+00:00",
            "media_type": "video",
            "metadata": {
                "author": "Levi",
                "category": null,
                "custom_params": {},
                "description": "A surfer pulls up in a camper van with a board on top at daybreak on a dirt road in a coastal area",
                "language": null,
                "permalink": "",
                "publish_end_date": null,
                "publish_start_date": "2021-07-21T14:33:00+00:00",
                "tags": [],
                "title": "Daybreak"
            },
            "mime_type": null,
            "relationships": {
                "protection_rule": {
                    "id": "zyxw0987",
                    "type": "protection_rule"
                }
            },
            "schema": null,
            "source_url": null,
            "status": "ready",
            "trim_in_point": null,
            "trim_out_point": null,
            "type": "media"
        },
        ...
    ],
    "page": 1,
    "page_length": 400,
    "total": 80
}
  1. Capture the media[].id for each media item returned.

  1. Make a PATCH https://api.jwplayer.com/v2/sites/{site_id}/media/{media_id}/ for each media ID in which the category in the JSON payload must be updated.
curl -g -X PATCH 'https://api.jwplayer.com/v2/sites/{site_id}/media/{media_id}/' \
     -H 'Authorization: Bearer {v2_api_secret}' \
     -H 'Content-Type: application/json' \
     -d '{"metadata": {"category": "Pop Culture"}}'

import requests
import json

url = "https://api.jwplayer.com/v2/sites/{site_id}/media/{media_id}/"

payload = json.dumps({
  "metadata": {
    "category": "Pop Culture"
  }
})
headers = {
  'Authorization': 'Bearer {v2_api_secret}',
  'Content-Type': 'application/json'
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.json())


List all media items in a large library

User story: On average, PQRS Media publishes approximately 500 full videos, trailers, and teasers a month. Over the last five years they have created 29,264 videos, starting from January 2017. PQRS Media needs to create a list of all its videos for an internal audit. The list of videos must include the video title, description, author, and IAB category.

Objective: From PQRS Media's library, retrieve a JSON object for each video that includes the following media properties: metadata.title, metadata.description, metadata.author, and metadata.category.

Constraint: The Platform Management API returns an upper limit of 1,000 records per request.


  1. Make a GET https://api.jwplayer.com/v2/sites/{site_id}/media/?q=created:[2017-01-01 TO 2017-01-31]&page_length=1000 call.

    The q query (q=created:[2017-01-01 TO 2017-01-31]) restricts the list to only media items created during the month of January 2017.

    The page_length query parameter (page_length=1000) ensures that the Platform Management API displays all the media items created within the month range.
curl -g -X GET 'https://api.jwplayer.com/v2/sites/{site_id}/media/?q=last_modified:[2017-01-01 TO 2017-01-31]&page_length=1000' \
     -H 'Authorization: Bearer {v2_api_secret}'

import requests

url = "https://api.jwplayer.com/v2/sites/{site_id}/media/?q=last_modified:[2017-01-01 TO 2017-01-31]&page_length=1000"

payload={}
headers = {
  'Authorization': 'Bearer {v2_api_secret}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

  1. Loop the GET https://api.jwplayer.com/v2/sites/{site_id}/media/?q=created:[{start_date} TO {end_date}]&page_length=1000 call for each month until the current month.