Filtering

Most results that are paginated can also be filtered. This makes it easy to retrieve specific information, like the video assets on one board, but more specific queries are also possible. For example, you could fetch every 9:16 video from one generation run that has finished processing.

For example, to return all the videos in the workspace, you can use the following query:

query Videos($workspaceId: ID!) {
  assets(workspaceId: $workspaceId, filter: { types: [VIDEO] }) {
    edges {
      node {
        id
        displayName
      }
    }
  }
}

The above query leaves out videos that are still being generated. To include them, add the includeProcessing field:

query Videos($workspaceId: ID!) {
  assets(workspaceId: $workspaceId, filter: { types: [VIDEO], includeProcessing: true }) {
    edges {
      node {
        id
        displayName
        ... on Video {
          status
        }
      }
    }
  }
}

Each list has its own filter input with named fields. Set a field to narrow the list by it, and leave it out to ignore it. Values are matched exactly, and text is matched with the search argument instead.

Logical operators

By default, all fields described in the filter need to be matched. The filter merges all the conditions together using a logical and operator.

For example, the below example will find all starred boards that were shared with you:

query StarredSharedBoards($workspaceId: ID!) {
  boards(workspaceId: $workspaceId, filter: { starred: true, sharedWithMe: true }) {
    edges {
      node {
        id
        title
      }
    }
  }
}

There is no or keyword. To combine alternatives, run one query per alternative, or fetch the broader set and narrow it in code. Fields that take a list, such as types, aspectRatios and boardIds, match any of their values, so a single query can return images and videos at once.

Filtering by relationship

Data can also be filtered based on its relations. For example, you can filter assets by the board they are placed on, the generation run that made them, or the folder they are filed in. To query all the images on one board, you can execute the following query:

query BoardImages($workspaceId: ID!, $boardId: ID!) {
  assets(workspaceId: $workspaceId, filter: { types: [IMAGE], boardIds: [$boardId] }) {
    edges {
      node {
        id
        displayName
        ... on Image {
          board {
            title
          }
        }
      }
    }
  }
}

Tags are a many-to-many relationship and are filtered similarly. The following query will find assets that carry the product tag:

query ProductAssets($workspaceId: ID!) {
  assets(workspaceId: $workspaceId, filter: { tags: [{ value: "product" }] }) {
    edges {
      node {
        id
        displayName
      }
    }
  }
}

Examples

Find the finished 9:16 videos from one generation run, newest first:

query RunVideos($workspaceId: ID!, $runId: ID!) {
  assets(
    workspaceId: $workspaceId
    filter: { types: [VIDEO], aspectRatios: ["9:16"], runId: $runId }
    order: { field: CREATED, direction: DESC }
  ) {
    edges {
      node {
        id
        displayName
        ... on Video {
          downloadUrl
        }
      }
    }
  }
}

Find the images on a board that are tagged as a product shot:

query ProductShots($workspaceId: ID!, $boardId: ID!) {
  assets(
    workspaceId: $workspaceId
    filter: { types: [IMAGE], boardIds: [$boardId], tags: [{ value: "product" }] }
  ) {
    edges {
      node {
        id
        displayName
      }
    }
  }
}

Find the boards you starred, most recently changed first:

query StarredBoards($workspaceId: ID!) {
  boards(workspaceId: $workspaceId, filter: { starred: true }, orderBy: { field: UPDATED, direction: DESC }) {
    edges {
      node {
        id
        title
        updatedAt
      }
    }
  }
}

Find your favourite assets that were used in the last 30 days, and are not filed in any folder:

query RecentFavourites($workspaceId: ID!) {
  assets(workspaceId: $workspaceId, filter: { favourites: true, recentlyUsed: true, unfiled: true }) {
    edges {
      node {
        id
        displayName
        createdAt
      }
    }
  }
}