List and query Objects
Query Objects in the Bucket. This is the main read endpoint and also the way to fetch a single Object by slug: pass query={"type":"posts","slug":"my-post"} and read the first element of objects.
The query parameter is a URL-encoded JSON object following MongoDB comparison and logical operator syntax. Use props to limit the response to the fields you need, which matters because the API rejects responses over roughly 6 MB with a 413. Use depth to resolve Object Relationship Metafields into nested Objects. For large collections, prefer cursor pagination with after over large skip offsets.
Query parameters
The Bucket read key. Required unless the Bucket has no read key configured.
A short-lived JWT issued by the Cosmic dashboard (object editor > Preview). When present and valid, the request is treated as status=any so the latest draft is returned. Bound to one Bucket for one hour. Still requires read_key. Invalid or expired tokens return 401.
A URL-encoded JSON object used to filter results. Follows MongoDB comparison ($eq, $gt, $gte, $lt, $lte, $in, $all, $ne, $nin), evaluation ($regex with $options), and logical ($and, $or, $not, $nor) operators. Query Object Relationship Metafields by the related Object's id, not its slug.
Comma-separated list of properties to return, including nested metadata paths. Omit to return everything. Narrowing props is the main way to keep responses under the 6 MB response cap and to reduce latency.
Which version of each Object to return. any returns the latest draft or published version.
Sort order. Prefix with - for descending. Sorting by metadata.$key requires that Metafield to be marked sortable under Object type > Settings, and is limited to two sortable Metafields per type.
Maximum number of results to return.
Offset pagination: number of results to skip. Use after instead for large collections. Only one of skip and after may be used.
How many levels of Object Relationship Metafields to resolve into nested Objects. Circular references are rejected.
Cursor pagination: the id of the last Object from the previous page. Follows the current sort order with id as a tiebreaker, works with any sort except random, and is more efficient than large skip offsets. Only one of skip and after may be used.
Set to false to bypass the cache and read through to the database. Guarantees you see writes you just made, at the cost of higher latency.
Set to true to indent the JSON response for human reading. Increases response size.
Response
The matching Objects.
Changes
No recorded changes to this endpoint across all 1 revision of this API.