In most of the tutorials in our documentation and our public examples, you will find detailed instructions on how to configure various aspects of your encoding workflows with focus on producing output files that can be used directly for playback or for ingest into downstream systems. In this article however, we will focus on metadata about your encodings, and how to retrieve information about previously performed encodings, in particular for the purpose of auditing past performance, writing reports and to check on the health of your workflows.
This article also provides a few tips and tricks on how you can adjust your encoding configuration to improve your ability to retrieve specific information at a later stage.
# List of encodings
In most cases, and regardless of the information you are trying to obtain, you will want to obtain a list of encodings. Use the [list all encodings endpoint](🔗) for that purpose. In its most basic usage, it will return a list of the last 25 encodings that have been created in the account, in reverse order of creation (ie. with the newest coming first).
## Encoding Information returned
In addition to the fields that you set when creating the encoding (such as `
description` and `
labels`), and an `
id` field with a unique identifier generated by the platform, the payload returned for each encoding in the list will also contain essential information to determine its status:
status` with one of the following values (details about the meaning of each can be found [in this FAQ](🔗)):
CREATED` for encodings that have been configured but not started
QUEUED` for encodings that have been started, but are in a queue (either waiting for an encoding slot to be available, of for the encoder to be warmed up)
RUNNING` for encodings that are being performed
CANCELED` for encodings that were cancelled by the user
FINISHED` for encodings that successfully completed
ERROR` for encodings that failed
TRANSFER_ERROR` for encodings that completed, but failed in the last step when attempting to transfer the output files to the Output storage (and [here](🔗) is how you go about resolving those)
progress` contains a value between 0 and 100 depending on the progress of the encoding
timestamps for the most important stages in the encoding: `
runningAt` and `
finishedAt`. The latter reports the time when the encoding was completed, cancelled or stopped with an error.
Note that some encodings may also carry an `
errorAt`. Since release 1.50.0 of our API, this field has been deprecated, in favour of the combination of the `
finishedAt` property and `
status` property (set to `
ERROR`). It is however still included for backward compatibility
selectedEncoderVersion` states the version of the encoder used to perform the encoding. If a version tag such as `
STABLE` or `
BETA` was used when configuring the encoding (as is recommended), this field will provide the actual version used.
selectedCloudRegion` states the cloud provider and region in which the encoder performed the encoding. If the encoding was configured with `
AUTO`, this field is resolved to the actual region used.
# Query Filters
To retrieve only a logical subset of encodings, you can use query parameters when calling the [list all encodings](🔗) endpoint to filter the results.
## Status filter
If you want to return only a list of encodings with a particular status, use the status query parameter with one of the values listed above.
## Date filters
If you want encodings created or started within a certain time window, you can use and combine 6 datetime-based filters, which take ISO8601-formatted values:
createdAtNewerThan` and its counterpart `
startedAtNewerThan` and its counterpart `
finishedAtNewerThan` and its counterpart `
## Search filter
search` filter allows you to do a match on some of the metadata associated with the encoding, which at the time of writing this article comprises the `
name` and `
labels` fields. It also allows partial matching of strings (from the start of those metadata fields), by using the `
**Tip: Naming conventions**
To make best use of this filter, you need to ensure that you define metadata when you configure your encoding in such a way as to enable this type of metadata query down the line. Our recommendations are as follows:
Tag your encoding with one or more small labels that represents some important aspects of your encoding workflows that you may want to retrieve information about in a segmented way at a later stage, such as different encoding workflows, different targets, specific experiments you are performing, etc.
Alternatively, or additionally, prefix the encoding name with a short string that identifies similar or additional important aspects about the encoding for later retrieval
## Other parameters and filters
There are other parameters that may be useful for the purpose of tuning the results of the query:
type`: if you are using a mix of Live and VOD encodings in your account, you will want to set that filter to `
sort`: allows you to define the order in which the encodings are returned, by specifying a field and a direction (`
asc` or `
desc`). The most meaningful fields for this type of request are `
createdAt` and `
startedAt`. The default applied is `
selectedEncoderVersion`: to retrieve encodings performed with a specific encoder version.
selectedCloudRegion`: to retrieve encodings performed with a specific cloud provider and in a specific region.
A full list of other parameters can be found in the API documentation for the [List all encodings](🔗) endpoint.
Remember that if you are planning to pull information for a large number of encodings, the results will come in batches, by default of 25 items, and you will need to paginate through the results with the `
limit` and \`offset´ parameters. The first defines how many objects are returned in the response payload (with a maximum of 100), and the latter at what index to start returning results. Note that the payload returned for this type of query will always include a count of the total number of encodings that match the filters, as well as URLs to the next (and previous) batch of encodings for the applied filters.
#### Encodings with errors
To return the last 50 VOD encodings that failed, you would make a call to
Note that with our SDKs, query and filter parameters are typically provided as properties of a specific object that is passed as a single property to the `
list` method. The response from that endpoint would be a `
PaginationResponse` payload that contains pagination information and an array of `
For example, with the Java SDK, the query above would look like this:
#### Encodings performed on a specific day for a specific workflow
To return a full list of completed encodings in a specific 24 hour period in natural time order of creation of the encodings, for a labeled workflow and an experiment "A" (which was used as prefix to the encoding name):
This payload will only return the first 25 encodings. The call to get the next 25 would be
Let’s look at it in Python this time:
# Detailed status
To get more details about the status of your encoding, and in particular finer grained details about the various stages of the encodings, and details of warnings and errors that may have occurred, you will need to query the specific [status endpoint](🔗) for each encoding in turn. In addition to the same information as above, additional significant information in the response payload comprises:
subTasks` list the major phases in the encoding (eg. queue, file download, file analysis, encoding, muxing, etc.) and provide for each:
status and progress information
optionally metadata containing statistics relevant to the phase (eg. size of the download, number of bytes or frames encoded, etc.
messages` providing detailed information about stages reached in the encoding (info, debug), as well as errors and warnings
# Input information
In certain cases, you may want to be able to determine the spec of the input file (or files) that were used in your encodings, for example because you want to analyse the encoding performance in relation to the type of file you ingested, or you want to get an idea of why an encoding failed with a specific file, or understand [how a specific stream condition was applied](🔗).
When you configure an encoding, you provide information on how to access the input file directly or indirectly (through an `
IngestInputStream`) when creating the (output) Stream. Since it is possible to have different streams to use different files (for example, if audio and video input files are distinct), you may need to first [retrieve a list of streams](🔗) for your encoding and collect the identifier of the relevant stream(s) to go further.
## File path and Stream selection
Determining the file path and input stream selection parameters used when configuring the encoding will depend on whether the input file information was provided directly in the `
Stream` creation payload or as an `
IngestInputStream`. The difference is explained in [this FAQ](🔗). On that basis, you therefore need to either:
[retrieve the stream details](🔗) (which requires a stream identifier), and/or
[retrieve the ingest input streams](🔗) (which does not)
## File specification
The Bitmovin API also allows you to retrieve the details of the analysis of your input file, such as the list of streams found in the file, and their specification (for example, file size, duration, codecs, dimensions, channel format, etc.)
To retrieve this information, use the [stream input details endpoint](🔗) with your encoding ID and stream ID. Note that the information returned is for the whole input file, and does not take into consideration the stream selection configuration of your stream. This may be an advantage if all your streams use the same input file, as a single call will return all the information you might be interested in.
Here is an example of the type of input file analysis information returned:
**Note:** At the time of writing, it is only possible to get full details about the input files when the encoding only used 1 file per (output) stream. For use cases such as [concatenation of files](🔗), the information is not available for all files. This will be added in a future version of the API.\*