Skip to main content

Using Clip-Level Reporting

L1 Support Admin
  • Updated

Overview

Our clip-level reporting endpoint provides insight into your assets' clip-level metadata, generating reports for such uses as:

  • Generating lists commonly occurring topics, faces, and keywords, for use in video personalization menus and settings.

  • Filtering out content that may have been misidentified by your AI scan.

  • Monitoring your data ingestion workflow (especially useful if you are pulling in data from multiple data providers).

These reports are delivered instantly in a JSON format, so that they can be easily used to automatically update preference menus and other options in your personalization UI.

Accessing the Clip-Level Reporting Endpoint 

You can find the the relevant API specs and test out the functionality in the “Reporting” tab in the API tools on on lvs.linius.com.

Requesting Reports

Use the following endpoint to request reports.

  • GET /v3/reporting/clip/agg 

Request field definitions

Name

Description

x-api-key

Api key

Authorization

Bearer token

You can get both your API key and your bearer token on any GET endpoint in the API Tools: Try-It-Now form on lvs.linius.com (accessible via the left-navigation).

query

Enter a Lucene query to: search for a specific text string (e.g. word, phrase, or name) or asset ID; apply filters based on clip-level metadata (e.g. clip category or timecode range).

The table at the end of this page provides sample queries for a variety of reports.

aggregation

Determines how to organize your report records.

Available aggregation values:

  • PAYLOAD_CATEGORY (i.e. Clip Category)

  • PAYLOAD_VALUE (e.g. the unique Face name, topic, keyword or

  • PAYLOAD_INDEXER_TYPE (i.e. the data source)

  • ASSET_ID

size

Specify the maximum number of results.

  • Default is 100 records

  • Maximum # of records: 10,000.

minDocCount

The minimum # of times a specific payload value, clip category, or indexer type must match your Lucene query in order for it to appear within your report. (For example, you might use “
”minDocCount:2” if you want to restrict your report to unique faces names that appear more than once.)

 

 

Report Examples

 

Use Case

Sample Report

Get count of all face clips.

Query:

payload.category:FACE

Aggregation:

PAYLOAD_CATEGORY

[ { "key": "FACE", "value": 1416 }, { "key": "ALIAS", "value": 3 } ]

 

List of top 10 unique names for all KNOWN Faces (i.e. filtering out “Unknown” faces).

Query:

+payload.category:FACE -payload.value:Unknown

Aggregation:

PAYLOAD_VALUE

[ { "key": "Richard Drax", "value": 52 }, { "key": "Amy Klobuchar", "value": 40 }, { "key": "Paul Walker", "value": 24 }, { "key": "Pete Buttigieg", "value": 24 }, { "key": "Joe Biden", "value": 15 }, { "key": "Poppy Harlow", "value": 14 }, { "key": "Alan Duncan", "value": 13 }, { "key": "Boris Johnson", "value": 13 }, { "key": "Dominic Raab", "value": 13 }, { "key": "Phillip Lee", "value": 13 } ]

 

Get counts of all clips for each and every category

Query:

(leave blank)

Aggregation:

PAYLOAD_CATEGORY
 

[ { "key": "TEST_CATEGORY", "value": 36003 }, { "key": "KEYWORD", "value": 7044 }, { "key": "TAG", "value": 4637 }, { "key": "ASSET_TAG", "value": 2018 }, { "key": "TRANSCRIPT", "value": 1718 }, { "key": "FACE", "value": 1416 }, { "key": "TOPIC", "value": 1005 }, { "key": "SHOT", "value": 269 }, { "key": "ASSET_END_DATE", "value": 220 }, { "key": "ASSET_START_DATE", "value": 118 }, { "key": "BRAND", "value": 111 }, { "key": "SCENE", "value": 81 }, { "key": "", "value": 7 }, { "key": "TRANSCRIPT", "value": 4 }, { "key": "Transcript", "value": 4 }, { "key": "ALIAS", "value": 3 }, { "key": "My", "value": 3 } ]

 

Please note that any you ALIAS values that you add to your FACE clips will appear in your reports for any query that includes the FACE clip category.

 

 

Get counts of all clips for selected clip categories. (e.g FACE, TRANSCRIPT, and TOPIC)

Query:

payload.category:FACE TRANSCRIPT TOPIC

Aggregation:

PAYLOAD_CATEGORY
[ { "key": "FACE", "value": 1416 }, { "key": "TOPIC", "value": 7 }, { "key": "ALIAS", "value": 3 }, { "key": "TRANSCRIPT", "value": 1 } ]

 

Get counts of all clips containing a specific word, broken down by clip categories. (E.g. get all clips containing “John”)

Query:

payload.value:John

Aggregation:

PAYLOAD_CATEGORY
Get counts of all clips, broken down by clip category for one or more specific assets

Get counts for each unique Face containing value “John”

Query:

payload.category:FACE AND payload.value:John

Aggregation:

PAYLOAD_VALUE

 

Click for Sample

[ { "key": "John King", "value": 11 }, { "key": "John Bercow", "value": 4 }, { "key": "джон берков", "value": 1 } ]

 

Get counts of all clips, broken down by clip category for one or more specific assets.

Query:

+assetId:2958489

Aggregation:

PAYLOAD_CATEGORY
[ { "key": "KEYWORD", "value": 1279 }, { "key": "TAG", "value": 105 }, { "key": "TRANSCRIPT", "value": 40 }, { "key": "SHOT", "value": 22 }, { "key": "FACE", "value": 21 }, { "key": "TOPIC", "value": 21 }, { "key": "SCENE", "value": 6 }, { "key": "ASSET_TAG", "value": 1 } ]

 

Get counts for each unique KNOWN face within a specific assets.

Query:

+payload.category:FACE +assetId:2958528 2958489 -payload.value:Unknown

Aggregation:

PAYLOAD_VALUE
[ { "key": "Amy Klobuchar", "value": 8 }, { "key": "Pete Buttigieg", "value": 8 } ]

 

Get a count of topics contained within assets with Asset-level tag “politics”

Query:

You can use a two-step process like this:

  • Use asset management APIs (e.g. GET] /v3/asset) to retrieve assets containing asset-level tag “politics”

  • Use these asset IDs in this reporting query:
    +assetId:2958528 2958489 +payload.category:TOPIC

Aggregation:

PAYLOAD_VALUE

[

{

"key": "Political Campaigns and Elections",

"value": 4

},

{

"key": "Gun Control",

"value": 4

},

{

"key": "US Presidential Election",

"value": 4

},

{

"key": "Government Leaders and Politicians",

"value": 3

},

{

"key": "Republican Party U S",

"value": 3

{

"key": "US Congress",

"value": 3

}

]

Get a count of top 10 unique face clips with at least a 99% MSVI confidence score.

Query:

+payload.category:FACE +payload.confidence: [.99 TO *]

Aggregation:

PAYLOAD_VALUE
[ { "key": "Amy Klobuchar", "value": 16 }, { "key": "Pete Buttigieg", "value": 16 }, { "key": "Richard Drax", "value": 8 }, { "key": "Bernie Sanders", "value": 6 }, { "key": "Alan Duncan", "value": 2 }, { "key": "Boris Johnson", "value": 2 }, { "key": "Dominic Raab", "value": 2 }, { "key": "Mila Kunis", "value": 2 }, { "key": "Phillip Lee", "value": 2 }, { "key": "William Hague", "value": 2 } ]

 

Count clips for assets created since a specific a date. (e.g all clips since January 1 2012) broken down by category

Query:

+assetCreated: [1577846351000 TO *]

Aggregation:

PAYLOAD_CATEGORY
[ { "key": "KEYWORD", "value": 5013 }, { "key": "TAG", "value": 1255 }, { "key": "ASSET_TAG", "value": 572 }, { "key": "TRANSCRIPT", "value": 467 }, { "key": "FACE", "value": 320 }, { "key": "SHOT", "value": 269 }, { "key": "TOPIC", "value": 236 }, { "key": "SCENE", "value": 81 }, { "key": "BRAND", "value": 15 }, { "key": "ASSET_END_DATE", "value": 12 }, { "key": "ASSET_START_DATE", "value": 12 } ]

 

Count clips based on CLIP CREATION DATE ed since a specific a date. (e.g all clips since January 1 2012) broken down by category

Query:

+created: [1577846351000 TO *]

Aggregation:

PAYLOAD_CATEGORY
[ { "key": "KEYWORD", "value": 5172 }, { "key": "TAG", "value": 1509 }, { "key": "TRANSCRIPT", "value": 547 }, { "key": "FACE", "value": 452 }, { "key": "SHOT", "value": 361 }, { "key": "TOPIC", "value": 292 }, { "key": "SCENE", "value": 108 }, { "key": "BRAND", "value": 22 } ]

 

Count clips containing specific word, broken down by category, EXCEPT for certain clip categories (e.g. search for trump, exclude certain clip categories ASSET_TAG, START_DATE, END_DATE)

Query:

+payload.value:Trump -payload.category:KEYWORD -payload.category:BRAND -payload.category:TOPIC

Aggregation:

PAYLOAD_CATEGORY
[ { "key": "TRANSCRIPT", "value": 8 }, { "key": "FACE", "value": 2 }, { "key": "", "value": 0 }, { "key": "ALIAS", "value": 0 }, { "key": "ASSET_END_DATE", "value": 0 }, { "key": "ASSET_START_DATE", "value": 0 }, { "key": "ASSET_TAG", "value": 0 }, { "key": "BRAND", "value": 0 }, { "key": "KEYWORD", "value": 0 }, { "key": "My", "value": 0 }, { "key": "SCENE", "value": 0 }, { "key": "SHOT", "value": 0 }, { "key": "TAG", "value": 0 }, { "key": "TANSCRIPT", "value": 0 }, { "key": "TEST_CATEGORY", "value": 0 }, { "key": "TOPIC", "value": 0 }, { "key": "Transcript", "value": 0 } ]

 

Get counts of all clips, broken down by all categories EXCEPT for certain clip categories.

Query:

payload.category:KEYWORD -payload.category:BRAND -payload.category:TOPIC

Aggregation:

PAYLOAD_CATEGORY

[ { "key": "TEST_CATEGORY", "value": 36003 }, { "key": "TAG", "value": 4637 }, { "key": "ASSET_TAG", "value": 2018 }, { "key": "TRANSCRIPT", "value": 1718 }, { "key": "FACE", "value": 1416 }, { "key": "TOPIC", "value": 1005 }, { "key": "SHOT", "value": 269 }, { "key": "ASSET_END_DATE", "value": 220 }, { "key": "ASSET_START_DATE", "value": 118 }, { "key": "SCENE", "value": 81 }, { "key": "", "value": 7 }, { "key": "TANSCRIPT", "value": 4 }, { "key": "Transcript", "value": 4 }, { "key": "ALIAS", "value": 3 }, { "key": "My", "value": 3 } ]

 

Related articles

Comments

0 comments

Article is closed for comments.