Query aspects
Query aspects in the Media Library dataset.
When you create and deploy an aspect, it's stored in the Media Library dataset alongside your asset documents. In this guide, you'll query your Media Library based on your aspects.
Prerequisites:
- API version v2025-02-19 or later
The examples below use JavaScript's fetch to perform API calls, but the same principles apply regardless of the language or request library.
List all aspects
Aspects are Sanity documents with a _type of sanity.asset.aspect. You can query them with GROQ using the Media Library's query endpoint.
const mediaLibraryId = '<your-library-id>'
const token = '<your-auth-token>'
const query = `*[_type == 'sanity.asset.aspect'] { ... }`
await fetch(`https://api.sanity.io/v2025-02-19/media-libraries/${mediaLibraryId}/query?query=${query}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`
}
})Like other Sanity queries, you'll receive a response containing the original query, a result, sync tags, and the response time. Here's an example response for a single field, boolean aspect:
{
"query": "*[_type == 'sanity.asset.aspect'] { ... }",
"result": [
{
"_type": "sanity.asset.aspect",
"definition": {
"type": "boolean",
"initialValue": false,
"name": "placeholder",
"description": "Set to true for temporary placeholder assets.",
"title": "Placeholder"
},
"_id": "placeholder",
"_updatedAt": "2025-04-15T23:21:59Z",
"_system": {
"createdBy": "gvRshKueQ"
},
"_createdAt": "2025-04-15T23:16:59Z",
"_rev": "liBwLfU12KkZimf6bVlggr"
}
],
"syncTags": [
"s1:W7DfKQ"
],
"ms": 3
}Query assets by aspect details
Any asset document in your library that has an assigned aspect will include those aspect details in an aspects property. You can query for specific aspect information using GROQ and the Media Library's query endpoint.
As an example, if you want to query all assets that have the placeholder aspect set to true, you can perform the following query.
const mediaLibraryId = '<your-library-id>'
const token = '<your-auth-token>'
// You may need to encode your query to pass it as a query string.
const query = encodeURIComponent(`*[_type == 'sanity.asset' && (defined(aspects.placeholder) && true == aspects.placeholder)]`)
await fetch(`https://api.sanity.io/v2025-02-19/media-libraries/${mediaLibraryId}/query?query=${query}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`
}
})The above request returns any sanity.asset document with the placeholder aspect set to true.
POST instead of GET
You can also query with a POST request. Instead of using the ?query= parameter, set the body to your stringified query, the method to POST, and the Content-type to application/json. Here's the same example above, but as a POST.
const mediaLibraryId = '<your-library-id>'
const token = '<your-auth-token>'
const query = `*[_type == 'sanity.asset' && (defined(aspects.placeholder) && true == aspects.placeholder)]`
await fetch(`https://api.sanity.io/v2025-02-19/media-libraries/${mediaLibraryId}/query`, {
method: 'POST',
body: JSON.stringify({query}),
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
})Was this page helpful?