Search for Assets

How to find a needle in a haystack


Overview

Frame.io's API supports deep, faceted search for Assets across an entire Account, mirroring the functionality in the web application. While the most commonly useful filters are Team, Project, and Status, filters and sorting can be combined in unique ways to produce extremely specific, API-driven sets. In general, all filters aside from the account_id, q (query), and sort follow the same structure, and all are explained below.

search-filters.png

Mismatch between requested and returned page sizes

As of March, 2022, there is known a bug affecting the search API's paging function. Until this bug is addressed, we do not recommend using the search API to iterate over multiple pages of results (i.e. more than 100 assets), because the requested page size may not correspend with actual returned asset count.

Defaults

The API request to trigger a search is always the same:

It's always the same request

POST to https://api.frame.io/v2/search/library

If not supplied explicitly, default values for search tuning are as follows:

AttributeDefault valueDescription
page_size1010 Assets will be returned per page.
page1The query will return the first page of the response.
sortrelevance"Relevance" attempts to order assets based on a specifically tuned set of attributes. In the absence of a query, relevance is heavily skewed toward upload recency.

About this guide

This guide walks through the process of building a search query that matches:

  • Assets within an Account
  • That matches the query "moon"
  • Is in a specific Project
  • Was uploaded between April 1st and 30th, 2020
  • And has been "Approved"

The body for our search will end up looking like this:

JSON
{
    "account_id": "<account_id>",
    "q": "moon",
    "sort": "name",
    "filter": {
        "inserted_at": [
            {
                "op": "gte",
                "value": "2020-04-01T04:00:00.000Z"
            },
            {
                "op": "lte",
                "value": "2020-04-30T03:59:59.999Z"
            }
        ],
        "project_id": {
            "op": "eq",
            "value": "<project_id>"
        },
        "label": {
            "op": "eq",
            "value": "approved"
        }
    },
    "page_size": 10,
    "page": 1
}

Account, query and sort

The Account (account_id), query (q), and sort are the three most basic building blocks that sit outside of any filter attributes in a search query.

Account context

Technically, the only attribute you need to perform a search is an account_id. Doing so will simply pull every Asset (including folders) on the Account, with default pagination values (10 Assets per page, starting on page 1).

JSON
{
    "account_id": "<account_id>"
}

Search query

The next most common (and helpful) attribute to include is the query itself. Note: because Frame.io's API search accepts a null query, there is no need for a wildcard (*) query. You're either searching for something, or you're requesting a (potentially filtered) sort of all Assets in an Account.

In our case, we'll be searching for the term "moon".

JSON
{
    "account_id": "<account_id>",
    "q": "moon"
}

Sorting

sort.png

Frame.io supports a number of different sorting options. The syntax for sort order is similar across options:

  • There is a default sort direction
  • To reverse that direction, prefix the sort value with a negative -

For example, to sort in reverse alphabetical order (Z to A), you would declare "sort": "-name".

The default sort operation is "Relevance." Accordingly, it does not need to be declared, and will be assumed if no sort attribute is provided.

Sort optionAttributeDefault direction
Relevancen/an/a
Date uploadedinserted_atOldest first
NamenameA to Z
SizefilesizeSmallest first
Uploadercreator.nameA to Z

Accordingly, as we build out our query, we can now add in our sort for name, A to Z:

JSON
{
    "account_id": "<account_id>",
    "q": "moon",
    "sort": "name"
}

Filters and pagination

Filters are both the trickiest, and most powerful feature of Frame.io's Asset search. Filters are written within a single filter object, and all follow the same pattern of an operation (op), and a value. Filters will use the following common abbreviations, with equivalency options other than "equals" reserved for date and size queries:

  • eq -- equals
  • lt -- less than
  • gt -- greater than
  • lte -- less than or equal to
  • gte -- greater than or equal to
  • match -- exact match, used only for Uploader and Filetype filters

For example, a filter to match on a known project_id would be constructed as follows:

JSON
{
    "filter": {
        "project_id": {
            "op": "eq",
            "value": "<project_id>"
        }
    }
}

Options and operations

The following table describes the options and operations associated with each filter type.

Filter optionAttributeSupported operationsSupported values
Archivedarchivedeqtrue, false
Date uploadedinserted_ateq, lt, gt, lte, gte<datetime> (ISO-8601, UTC)
Deleteddeletedeqtrue, false
File typefiletypematch<MIME type>
Privateprivateeqtrue, false
Projectproject_ideq<project_id>
Sizefilesizeeq, lt, gt, lte, gtesize (in bytes)
Statuslabeleqnone, in_progress, needs_review, approved
Teamteam_ideq<team_id>
Typeasset_typeeqaudio, document, folder, image, other, stream, video
Uploadercreator.namematch<name>

To continue building out our query, we can now add a filter for Assets that are:

  • Is in a specific Project
  • Uploaded between April 1st and 30th, 2020
  • Marked as "Approved"
JSON
{
    "account_id": "<account_id>",
    "q": "moon",
    "sort": "name",
    "filter": {
        "inserted_at": [
            {
                "op": "gte",
                "value": "2020-04-01T04:00:00.000Z"
            },
            {
                "op": "lte",
                "value": "2020-04-28T03:59:59.999Z"
            }
        ],
        "project_id": {
            "op": "eq",
            "value": "<project_id>"
        },
        "label": {
            "op": "eq",
            "value": "approved"
        }
    }
}
Pagination

The search endpoint paginates exactly as any other endpoint, via page_size and page attributes that sit at the outermost layer of the request body. For more details on pagination, please refer to the separate guide here.