Retrieve recordings for a season

Request

To retrieve the recordings for a specific season of a series, send a GET request to:

CODE

https://<host>:<port>/cdvr/v2/recordings/seasons/{seasonId}

This returns all the recordings (and recording requests) for the specified season.

You can get the season ID by getting the seasons for a series for which the user has recordings.

This API supports:

Limiting the number of records returned
Paging
Filtering the results

Headers

Content-Type: application/json
Authorisation

Mandatory arguments

seasonId – the ID of the season

Optional arguments (in URL)

limit – the number of records to return
page – the page number to return (cannot be used without limit)
For example:
- ?limit=10 returns the first 10 recordings.
- ?limit=10&page=2 returns the second 10 recordings.
sort – the sort order of the returned recordings. It can be one of:
- CHRONOLOGICAL_ASC
- CHRONOLOGICAL_DESC
- EXPIRATION_ASC
- EXPIRATION_DESC
- DURATION_ASC
- DURATION_DESC
- METADATA_ASC
- METADATA_DESC
sortField – the metadata field used for sorting if METADATA_ASC or METADATA_DESC is specified in sort. It can be one of:
- TITLE
- SYNOPSIS
- DESCRIPTION
- SEASON_NUMBER
- EPISODE_NUMBER
- EPISODE
- DEFINITION
- YEAR
sortLocale – the locale to be used for sorting. Only required if METADATA_ASC or METADATA_DESC is specified in sort.
genericSort – generic sort that allows you to sort the results by one or more fields. If you specify multiple fields, the results will be sorted by the first specified field, then the second, and so on.
You must append :1 or :-1 to specify whether the sort is ascending (1) or descending (1-).
For example, to sort by title, then series number, then episode number, add this to the query:
CODE
```
&genericSort={
     "programmeMetaData.title":1,
     "programmeMetaData.editorial.seriesRef":1,
     "programmeMetaData.editorial.episodeNumber":1
}
```
statuses – filters based on recording status. Available values are:
- SCHEDULED
- RECORDING
- RECORDED
- FAILED
- NEW
To specify multiple values (e.g., if you want to get both scheduled and recorded requests), use the statuses parameter as many times as required.
For example:
?statuses=SCHEDULED&statuses=RECORDED
filter – a generic filter that allows you to filter the results based on the value of any field
fields – the fields to include in the response
locale – the locale to filter by. If not specified, the default locale will be used. If neither the specified nor the default locale is available, all locales will be returned. Note that the 'none' metadata locale is common in all instances.
deviceType – the device type to filter by

Response

A successful request returns an HTTP 200 status.

A bad request returns an HTTP 400 status.

An unauthorised request returns an HTTP 401 status.

If the requested season does not exist, the request returns an HTTP 404 status.

Example

A successful request returns a payload that looks like this:

JSON

{
    "totalRecords": 2,
    "recordingSet": [{
            "id": "c0e95b3c-ac19-4f15-b1ca-6f889766d7ae",
            "eventId": "NPVR_EP03",
            "start": "2025-02-05T09:00:00Z",
            "end": "2025-02-05T10:00:00Z",
            "captureStart": "2025-02-05T08:55:00Z",
            "captureEnd": "2025-02-05T10:05:00Z",
            "status": "RECORDED",
            "channelId": "pech01_prech01",
            "duration": 3600,
            "seriesRecordingId": "aa2a5464-8447-497d-9ef8-2da4b336491a",
            "captureDuration": 4200,
            "csaiAdCueTimes": [],
            "availability": {
                "start": "2025-02-05T10:00:00Z",
                "end": "2025-02-20T10:00:00Z"
            },
            "contentId": "series1_season01_Episode03",
            "contentType": "movie",
            "seriesId": "series_cgprid01",
            "seasonId": "series_cgprid01_season01",
            "isReschedule": false,
            "isProtected": false,
            "productRefs": [
                "testProduct001"
            ],
            "ratingPrecedence": {
                "predecessor": null,
                "successor": null
            },
            "playback": {
                "iOS": {
                    "drmId": "12",
                    "technicalId": "ptch02_prtch02",
                    "uri": "http://cdn.nagra.vision",
                    "isStorageAllowed": false,
                    "dynamicRange": []
                },
                "Android": {
                    "drmId": "12",
                    "technicalId": "ptch01_prtch01",
                    "uri": "http://cdn.nagra.vision",
                    "isStorageAllowed": false,
                    "dynamicRange": []
                }
            },
            "images": {},
            "InHomeBlockingRequired": true,
            "guardTime": {
                "startSecs": 300,
                "endSecs": 300,
                "source": "CHANNEL"
            },
            "isPartiallyRecorded": false,
            "metadata": {
                "en_GB": {
                    "Description": null,
                    "year": null,
                    "episode": null,
                    "title": "LTCU JITP EP03",
                    "PromoImages": [
                        "ThirdSeasonFirstEpisodeImage.jpg"
                    ],
                    "episodeNumber": 3,
                    "Ratings": null,
                    "Language": null,
                    "definition": null,
                    "categories": [
                        "Adventure",
                        "Drama"
                    ],
                    "SeasonNumber": 0,
                    "contentRef": "series1_season01_Episode03",
                    "editorial": {
                        "deviceType": null,
                        "Rating": {
                            "code": "1",
                            "precedence": null,
                            "Title": "1",
                            "ratingBody": null
                        },
                        "media": null,
                        "locale": "en_GB",
                        "episodeNumber": 3,
                        "Synopsis": null,
                        "duration": 4200,
                        "seriesRef": "series_cgprid01",
                        "Episode": null,
                        "companyId": "series1_season01",
                        "nls": null,
                        "technicals": [],
                        "id": "series1_season01_Episode03",
                        "_id": "series1_season01_Episode03"
                    },
                    "isLtcu": true,
                    "period": {
                        "duration": 3600,
                        "end": 1738749600,
                        "start": 1738746000
                    },
                    "editorialContentLinkId": null,
                    "ETV_display": null,
                    "Title": "event ep 13 title",
                    "synopsis": null,
                    "isNew": null,
                    "serviceRef": "pech01_prech01",
                    "HDChannel": null,
                    "ModelType": null,
                    "Genre": null,
                    "isnPvr": true,
                    "Audio": [],
                    "BlackedOutInternet": null,
                    "SeriesTitle": "I Love Lucy"
                }
            },
            "creationDate": "2025-02-05T11:18:00Z",
            "modifiedDate": "2025-02-05T11:18:56Z",
            "isjitp": true,
            "sourceId": "source1",
            "networkLocation": "http://cdn.nagra.vision/hls/live/technical channel name 01 v1/28107e25-309c-a557-2f4e-ea2000868a6e/index.m3u8",
            "recordId": "d326ade9-a62c-451b-9150-447f428dc37d"
        },
        {
            "id": "ea1b431c-ac6a-4f14-8240-0417aa1837c8",
            "eventId": "NPVR_EP06",
            "start": "2025-02-06T18:00:00Z",
            "end": "2025-02-06T19:00:00Z",
            "captureStart": "2025-02-06T17:55:00Z",
            "captureEnd": "2025-02-06T19:05:00Z",
            "status": "SCHEDULED",
            "channelId": "pech01_prech01",
            "duration": 3600,
            "seriesRecordingId": "aa2a5464-8447-497d-9ef8-2da4b336491a",
            "captureDuration": 4200,
            "csaiAdCueTimes": [],
            "availability": {
                "start": "2025-02-06T19:00:00Z",
                "end": "2025-02-21T19:00:00Z"
            },
            "contentId": "series1_season01_Episode01",
            "contentType": "movie",
            "seriesId": "series_cgprid01",
            "seasonId": "series_cgprid01_season01",
            "isReschedule": false,
            "isProtected": false,
            "productRefs": [
                "testProduct001"
            ],
            "ratingPrecedence": {
                "predecessor": null,
                "successor": null
            },
            "playback": {
                "iOS": {
                    "drmId": "12",
                    "technicalId": "ptch02_prtch02",
                    "uri": null,
                    "isStorageAllowed": false,
                    "dynamicRange": []
                },
                "Android": {
                    "drmId": "12",
                    "technicalId": "ptch01_prtch01",
                    "uri": null,
                    "isStorageAllowed": false,
                    "dynamicRange": []
                }
            },
            "images": {},
            "InHomeBlockingRequired": true,
            "guardTime": {
                "startSecs": 300,
                "endSecs": 300,
                "source": "CHANNEL"
            },
            "isPartiallyRecorded": false,
            "metadata": {
                "en_GB": {
                    "Description": null,
                    "year": null,
                    "episode": null,
                    "title": "LTCU JITP EP06",
                    "PromoImages": [
                        "FirstEpisodeImage.jpg"
                    ],
                    "episodeNumber": 1,
                    "Ratings": null,
                    "Language": null,
                    "definition": null,
                    "categories": [
                        "Adventure",
                        "Drama"
                    ],
                    "SeasonNumber": 0,
                    "contentRef": "series1_season01_Episode01",
                    "editorial": {
                        "deviceType": null,
                        "Rating": {
                            "code": "1",
                            "precedence": null,
                            "Title": "1",
                            "ratingBody": null
                        },
                        "media": null,
                        "locale": "en_GB",
                        "episodeNumber": 1,
                        "Synopsis": null,
                        "duration": 4200,
                        "seriesRef": "series_cgprid01",
                        "Episode": null,
                        "companyId": "series1_season01",
                        "nls": null,
                        "technicals": [],
                        "id": "series1_season01_Episode01",
                        "_id": "series1_season01_Episode01"
                    },
                    "isLtcu": false,
                    "period": {
                        "duration": 3600,
                        "end": 1738868400,
                        "start": 1738864800
                    },
                    "editorialContentLinkId": null,
                    "ETV_display": null,
                    "Title": "event ep 11 title",
                    "synopsis": null,
                    "isNew": null,
                    "serviceRef": "pech01_prech01",
                    "HDChannel": null,
                    "ModelType": null,
                    "Genre": null,
                    "isnPvr": true,
                    "Audio": [],
                    "BlackedOutInternet": null,
                    "SeriesTitle": "I Love Lucy"
                }
            },
            "creationDate": "2025-02-05T11:18:46Z",
            "modifiedDate": "2025-02-05T11:18:47Z",
            "isjitp": true,
            "sourceId": "source1",
            "networkLocation": "http://cdn.nagra.vision/hls/live/technical channel name 01 v1/28107e25-309c-a557-2f4e-ea2000868a6e/index.m3u8",
            "recordId": "ceb405fd-5c90-413f-acc2-e070a2c51410"
        }
    ]
}