Ooyala Ingestion Log API

version v2

https://api.ooyala.com/v2/ingestion

Overview

The Ingestion Log API is a RESTful API for tracking the status of ingested assets. Manifests (XML & CSV), thumbnails, closed-captions and videos are the assets in which log information is captured and searchable by ID, status and time period (filter options). At any given point of the ingestion process, the status of a file can be easily determined. Details of each filter option are provided in the following sections. For additional information on ingestion, please refer to the Ingestion documentation.

Authentication

Every request made to Ooyala's APIs requires three querystring parameters for authentication:

api_key - a user-specific key found in the Developers tab of Backlot.
expires - a UNIX timestamp (seconds since Jan 1st, 1970) indicating when your request should be valid until.
signature - a computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

See this documentation for more information related to authentication/request signing and usage of the Ooyala SDK.

Filtering by ID

Filtering by ID (External ID) allows the retrieval of log information for files related to a custom identifier. For additional information on external identifiers please refer to Using External Identifiers.

Filtering by File Name

Filtering by file name allows the retrieval of log information for a specific file (manifest, video, closed-caption or thumbnail) by its name.

Local/Non-Remote Files

For non-remote files, if the URL/path contains one or more sub-directories, the sub-directories must be provided when searching for the file. For example, the file named ep1.mp4 in ooyala-season1/ep1.mp4 is stored under directory ooyala-season1 which will result in the following path: ooyala-season1/ep1.mp4. When searching for this file, the entire path ooyala-season1/ep1.mp4 not ep1.mp4 must be provided. URL-encoded, the file name will become ooyala-season1%2Fep1.mp4 and the API call would look similar to

https://api.ooyala.com/v2/ingestion/logs?api_key=56O873TEDF6547BVR34R5H8.14-ms&expires=1930294539&file_name=ooyala-season1%2Fep1.mp4&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28

Remote Files

If the file is remote, meaning, the URL/path to the file exists at a remote location; the entire path to the file must be provided when searching. For example, the following XML manifest contains one item that consists of a video, thumbnail and closed-caption. Each URL/HREF of these files point to a remote location.

<rss xmlns:media="http://search.yahoo.com/mrss/" 
     xmlns:dcterms="http://purl.org/dc/terms/" 
     xmlns:fh="http://purl.org/syndication/history/1.0" 
     xmlns:ooyala="http://www.ooyala.com/mrss/" version="2.0">
 <channel>
  <item>
   <media:title>Sample 1</media:title>
   <media:description>Sample 1 Remote Files</media:description>
   <media:content duration="65000" url="http://www.ooyala.com/Ingest/sample1.mp4" />
   <media:thumbnail url="http://www.ooyala.com/Ingest/sample1.png" />
   <media:subTitle href="http://www.ooyala.com/Ingest/sample1.dfxp"/>
  </item>
 </channel>
</rss>

When searching for a video by name, the entire URL: http://www.ooyala.com/Ingest/sample1.mp4 not sample1.mp4 must be specified. URL-encoded, the file name will become http%3A%2F%2Fwww.ooyala.com%2FIngest%2Fsample1.mp4 and the API call would look similar to

https://api.ooyala.com/v2/ingestion/logs?api_key=56O873TEDF6547BVR34R5H8.14ms&expires=1930294539&file_name=http%3A%2F%2Fwww.ooyala.com%2FIngest%2Fsample1.mp4&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28

Filtering by Status

Listed below are the statuses a file can have during the ingestion workflow process. When filtering by status, an optional time period can be included. If no time period is specified, last_1hour will be the default time period used to filter the results.

Supported Statuses

Status	Description
received	Indicates that the file has been received by the ingestion service. Note that remote assets `<media:remoteasset>` (XML manifest) or `content-type=remoteasset` (CSV manifest) will never be in the received state because the file is never ingested into the system.
processing	Once the file has been received, it becomes eligible for processing by the system. Processing indicates that for manifest, syntactical validation is taking place. for media files (video, thumbnail and closed-caption), ingestion into the Ooyala ecosystem is taking place.
file_waiting	Indicates that the manifest file (CSV or XML) has been ingested and processed and is waiting for the other files video, thumbnail and closed-caption to be ingested.
metadata_waiting	Media file (video, thumbnail or closed-caption) has been ingested and is waiting for the manifest file (CSV or XML) that contains the related metadata to be ingested.
done	When processed successfully, indicates that for manifest file, the manifest is syntactically valid. for video file, the file along with the metadata has been processed and an embed code has been assigned by the Ooyala ecosystem. for thumbnail and closed-caption files, the files have been ingested and associated with the video.
error	If an issue occurs while ingesting or processing a file, the status will go into an error state. In this case, the log information will include an error message detailing what went wrong. For manifest file, this indicates that it is syntactically invalid. For media file (video, thumbnail and closed-caption), this indicates that there was an issue processing the file.

Filtering by Time Period

Filtering by time period provides the ability to go back in time to view log information for one or more files. The filter options are either a period identifier (e.g. last_1hour) or start and end timestamp range (see tables below for details). When a period identifier (identifier) is used, we will use the current time as the starting point from which we go back in time. For example, if the current time is 2016-09-29 16:58:33 -0500 and the identifier=last_1month, the start time will be 2016-08-29 16:58:33 -0500 and the end time will be 2016-09-29 16:58:33 -0500.

Note: Unlike the other filter options (status and ID) where there is at most one log entry that is updated upon each status transition, filtering by time period provides historical information (similar to that of a log file); meaning, for each status a file transitions to, a separate log entry is created. In the following example where the time period filter option is used, the results contain 3 log entries for metadata.xml. Metadata.xml's status went from received to processing followed by done. The results represent the entire ingestion lifecycle of the file. If we were filtering by status or ID, we would only receive 1 log entry for metadata.xml in the results with a status of 'done' (current status of the file).

{
  "filter_params": {
    "period": "start=2016-11-07T14:48:27+00:00;end=2016-12-07T14:48:27+00:00"
  },
  "count": 3,
  "next_page_url": null,
  "results": [
    {
      "creation_time": "2016-12-04T01:38:48+00:00",
      "id": null,
      "file_name": "metadata.xml",
      "file_type": "manifest",
      "status": "done",
      "embed_code": null,
      "error_message": null
    },
    {
      "creation_time": "2016-12-04T01:38:42+00:00",
      "id": "unavailable",
      "file_name": "metadata.xml",
      "file_type": "manifest",
      "status": "processing",
      "embed_code": null,
      "error_message": null
    },
    {
      "creation_time": "2016-12-04T01:38:42+00:00",
      "id": "unavailable",
      "file_name": "metadata.xml",
      "file_type": "manifest",
      "status": "received",
      "embed_code": null,
      "error_message": null
    }]
}

Period Identifiers

Identifier	Description
last_1month	Go back one month from the current time.
last_1week	Go back one week from the current time.
last_1day	Go back one day from the current time.
last_12hours	Go back 12 hours from the current time.
last_1hour	Go back one hour from the current time. (Default if no other filter parameter/option is provided)

Start/End Timestamp Range

Timestamp range represents the start and end times to search for ingestion log information. Start time is required. End time is optional. If end time is not provided, the current time will be used in its place.

Example: start=2016-08-05T15:15:00-07:00;end=2016-08-05T16:00:00-07:00
URL-encoded: start%3D2016-08-05T15%3A15%3A00-07%3A00%3Bend%3D2016-08-05T16%3A00%3A00-07%3A00

Supported Date/Time Formats

Format	Example
YYYY-MM-DDThh:mm:ss.sTZD	start=2016-10-18T19:20:30.45+01:00;end=2016-10-20T19:20:30.45+01:00 URL encoded: start%3D2016-09-18T19%3A20%3A30.45%2B01%3A00%3Bend%3D2016-09-27T19%3A20%3A30.45%2B01%3A00
YYYY-MM-DDThh:mm:ss	start=2016-10-18T19:20:30;end=2016-10-20T19:20:30 URL encoded: start%3D2016-10-18T19%3A20%3A30%3Bend%3D2016-10-20T19%3A20%3A30
YYYY-MM-DDThh:mm	start=2016-10-18T19:20;end=2016-10-20T19:20 URL encoded: start%3D2016-10-18T19%3A20%3Bend%3D2016-10-20T19%3A20
YYYY-MM-DD	start=2016-10-18;end=2016-10-20 URL encoded: start%3D2016-10-18%3Bend%3D2016-10-20
YYYY/MM/DDThh:mm:ss.sTZD	start=2016/09/18T19:20:30.45+01:00;end=2016/09/27T19:20:30.45+01:00 start%3D2016%2F09%2F18T19%3A20%3A30.45%2001%3A00%3Bend%3D2016%2F09%2F27T19%3A20%3A30.45%2001%3A00
YYYY/MM/DDThh:mm:ss	start=2016/10/18T19:20:30;end=2016/10/20T19:20:30 start%3D2016%2F10%2F18T19%3A20%3A30%3Bend%3D2016%2F10%2F20T19%3A20%3A30
YYYY/MM/DDThh:mm	start=2016/10/18T19:20;end=2016/10/20T19:20 start%3D2016%2F10%2F18T19%3A20%3Bend%3D2016%2F10%2F20T19%3A20
YYYY/MM/DD	start=2016/10/18;end=2016/10/20 start%3D2016%2F10%2F18%3Bend%3D2016%2F10%2F20

URL-encoding

URL-encoding is the process of converting text within a URL into a format that enables it to be transmitted over the Internet. The following filter options must be URL-encoded prior to calling the API:

ID
File Name
Time Period

HTTP Response Codes

These are the HTTP response codes that can be returned for API responses. In case of errors, the API response body will explain the reason why the API returned an error response code.

Code	Description
`200` (OK)	Indicates that the GET request was handled successfully.
`400` (Bad Request)	Indicates that a request was poorly formed or contained invalid data. For example, the API would return a 400 response code if your request contained malformed or invalid parameters.
`401` (Unauthorized)	The necessary credentials were not provided.
`404` (Not Found)	Indicates that you have tried to access a resource that does not exist or use any method other than GET such as POST, PUT, DELETE, etc.
`500` (Internal Server Error)	Generic message that indicates that an unexpected error occurred while processing the request.

Logs

Retrieves a collection of ingestion log entries

/logs get

get

Retrieves log information for ingested files

Request
Response

Query Parameters

api_key: required (string)
User-specific key found in the Developers tab of Backlot

Example:
```
api_key=56O873TEDF6547BVR34R5H8.14-ms
```
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.

Example:
```
expires=1299991855
```
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Example:
```
signature=p9DG%2F%2BummS0YcTNOYHtykdjw5N2n5s81OigJfdgHPTA
```

file_name: (string)

Name of the file (manifest, closed-caption, thumbnail or video).

Example:

curl -X GET 'https://api.ooyala.com/v2/ingestion/logs?\
api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539\
&file_name=video1.mp4&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%\
2FPpDx2DwHNGyfko07%2B28'

id: (string)

Custom external identifier assigned to your assets.

Example:

curl -X GET 'https://api.ooyala.com/v2/ingestion/logs?\
api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539\
&id=12345678990'

period: (string)

Time in the past to retrieve log information. If no other filter parameter is specified, the API will default the filter to the last_1hour.

Example:

# Time period identifier
curl -X GET 'https://api.ooyala.com/v2/ingestion/logs?\
api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539\
&period=last_1month&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%\
2FPpDx2DwHNGyfko07%2B28'
# Time period date/time range 
curl -X GET 'https://api.ooyala.com/v2/ingestion/logs?\
api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539\
&period=start%3D2016-11-27T19%3A20%3A30.45%2B01%3A00%3Bend%\
3D2016-12-04T19%3A20%3A30.45%2B01%3A00&signature=p3RfmwGk%2FjwIup\
%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

status: (string)

Current status of the file within the ingestion workflow process. Optionally, period may be specified along with status. If period is not explicitly specified, last_1hour will be the default period.

Example:

curl -X GET 'https://api.ooyala.com/v2/ingestion/logs?\
api_key=ZnMmM6AO3CiBubra3R2Xd6pXHgK.28riq&expires=1930294539\
&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28\
&status=processing'
# Status w/ period identifier
curl -X GET 'https://api.ooyala.com/v2/ingestion/logs?\
api_key=ZnMmM6AO3CiBubra3R2Xd6pXHgK.28riq&expires=1930294539\
&period=last_1month&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FP\ 
pDx2DwHNGyfko07%2B28&status=processing'
# Status w/ period date/time range
curl -X GET 'https://api.ooyala.com/v2/ingestion/logs?\
api_key=ZnMmM6AO3CiBubra3R2Xd6pXHgK.28riq&expires=1930294539\
&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28&\
status=processing&period=start%3D2016-11-27T19%3A20%3\
A30.45%2B01%3A00%3Bend%3D2016-12-04T19%3A20%3A30.45%2B01%3A00\
&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Log resources in the APIs have this structure:

filter_params - The input parameters used to filter the log information (for informational purposes).
count - The number of log entries returned from the API call. If no entries were found, count will be 0.
next_page_url - (Pagination) The API is designed to return 100 results/log entries per request. If less than 100 results are found, next_page_url will be null; otherwise, next_page_url will consist of a unique URL that shall be used to retrieve the next 100 results. The URL consists of the previously provided parameters along with the page_state identifier needed to retrieve the next page of results. All values will be properly encoded so your client application can simply obtain this URL and use it to call the API again to retrieve the next page of results.
results - Array of log entries found based on the search criteria.

Results array has this structure:

file_type - The type of the file. Either manifest, thumbnail, caption or video
file_name - The name of the file excluding path information.
embed_code - System generated unique identifier for a video. Default value: null
id - User/System specified unique identifier (external ID) for a video. Applicable to manifest users only. Default value: null
creation_time - The time the log entry occurred.
status - The current status of the file. See table of available statuses.
error_message - If at any point of the ingestion workflow process an error occurs while processing the file, the status will be set to ‘error’ and an error message describing the issue will be available. Default value: null

Body

Type: application/json

Example:

{
  "filter_params": {
    "period": "start=2016-12-03T01:43:51+00:00;end=2016-12-04T01:43:51+00:00"
  },
  "count": 100,
  "next_page_url": "https://api.ooyala.com/v2/ingestion/logs?api_key=56O873TEDF6547BVR34R5H8.14-ms&expires=1480817631&paging_state=AC8ABAABlLcAABhkd2lja2VyK29pc3YyQG9veWFsYS5jb20AAAoyMDE2LTEyLTA0AABHAAgAAAFYx3uw0AAAJDRlNzRjNDYzLTQ4ZTQtNGFiOC05YzQ3LTM1NGYyNjk0NjM5NAAABGRhdGEAAAt3b3JrZmxvd19pZAB____6&period=start%3D2016-12-03T01%3A43%3A51%2B00%3A00%3Bend%3D2016-12-04T01%3A43%3A51%2B00%3A00&signature=p9DG%2F%2BummS0YcTNOYHtykdjw5N2n5s81OigJfdgHPTA",
  "results": [
    {
      "creation_time": "2016-12-04T01:38:51+00:00",
      "id": "42-12-04-2016",
      "file_name": "http://www.ooyala.com/Assets/cc_22404-updated.dfxp",
      "file_type": "caption",
      "status": "done",
      "embed_code": "lwcTAwODE6XoDW3iAz2KtBv7Adw_7Qhb",
      "error_message": null
    },
    {
      "creation_time": "2016-12-04T01:38:51+00:00",
      "id": "42-12-04-2016",
      "file_name": "http://www.ooyala.com/Ingest/video10.mp4",
      "file_type": "video",
      "status": "done",
      "embed_code": "lwcTAwODE6XoDW3iAz2KtBv7Adw_7Qhb",
      "error_message": null
    },
    {
      "creation_time": "2016-12-04T01:38:50+00:00",
      "id": "42-12-04-2016",
      "file_name": "http://www.ooyala.com/Assets/cc_22404.dfxp",
      "file_type": "thumbnail",
      "status": "error",
      "embed_code": "lwcTAwODE6XoDW3iAz2KtBv7Adw_7Qhb",
      "error_message": "Unable to download    
      http://www.ooyala.com/Assets/cc_22404.dfxp for 123456"
    },
    {
      "creation_time": "2016-12-04T01:38:48+00:00",
      "id": null,
      "file_name": "metadata.xml",
      "file_type": "manifest",
      "status": "done",
      "embed_code": null,
      "error_message": null
    }
    ...
    ]          
  }

HTTP status code 400

Body

Type: application/json

Example:

*Indicates that an unsupported period label was specified for ‘entered_period’.
{ 
 "error_message" :"Invalid period: '<entered_period>'. Must be  last_1month,last_1week, last_1day, last_12hours, last_1hour or start and end date time range"
}
*Occurs when searching by period and timestamp range was chosen but the start portion of the range was excluded.
{ "error_message" : "Period start time was not provided." }
*Occurs when searching by period and invalid timestamps for both start and end times were entered.
{ "error_message" : "Invalid period start and end times." }
*Occurs when searching by period and an invalid start time was entered.
{ "error_message" : "Invalid period start time: '<entered_start_time>}'" }
*Occurs when searching by period and an invalid end time s entered.
{ "error_message" : "Invalid period end time: '<entered_end_time>'" }
*Occurs when searching by period and the start time exceeds the current time.
{ "error_message" : "Period start time cannot be in the future." }
*Occurs when searching by period and the start time exceeds the end time.
{ "error_message" : "Period start time cannot exceed end time." }
*Indicates that an unsupported status was specified for ‘entered_status’.
{ "error_message" : "Invalid status: '<entered_status>'.  Must be one of the following: done, error, file_waiting, metadata_waiting, processing, received" }
*Indicates that there was not user found for the specified api_key.
{ "error_message" : "No user associated with the specified api_key." }
*Indicates that there was no provider found for the pcode retrieved from the specified api_key.
{ "error_message" : "No provider associated with pcode: '<pcode>'." }

HTTP status code 404

Indicates that an invalid endpoint or method other than [GET] was specified.

Body

Type: application/json

Example:

{ "error_message" : "Not Found" }

HTTP status code 500

General message in the event that some unexpected error occurs while processing the request. This generally will occur due to an issue with the service not necessarily related to the information provided to the service by the client.

Body

Type: application/json

Example:

{ "error_message" : "Internal error trying to retrieve log information for params ‘<list of input parameters>’" }

Ooyala Ingestion Log API

version v2

Local/Non-Remote Files

Remote Files

Supported Statuses

Period Identifiers

Start/End Timestamp Range

Supported Date/Time Formats

Logs

get /logs

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 404

Body

HTTP status code 500

Body