Data Access

Sorting & Pagination

Sort and paginate results from your collections.

Sort by a Single Field

Use the sort parameter to order results. Sort specifiers are objects with a field name key and a direction value of asc or desc.

Return articles sorted by newest first:

const articles = await client.Articles.readMany({
  fields: ['id', 'title', 'created_at'],
  sort: [{ created_at: { direction: 'desc' } }],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,created_at&sort[0][created_at][direction]=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/blog/items/articles?fields=id,title,created_at&sort[0][created_at][direction]=desc',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

Sort alphabetically by title (ascending is the default when direction is omitted):

const articles = await client.Articles.readMany({
  fields: ['id', 'title'],
  sort: [{ title: { direction: 'asc' } }],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title&sort[0][title][direction]=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/blog/items/articles?fields=id,title&sort[0][title][direction]=asc',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

The -field prefix syntax for descending sort (e.g., sort=-created_at) is not supported and will be rejected by the engine. Use the object syntax sort[0][field][direction]=desc instead.

Sort by Multiple Fields

Pass multiple sort specifiers to break ties. The second field only applies when values in the first field are equal.

Sort articles by status ascending, then by creation date descending within each status:

const articles = await client.Articles.readMany({
  fields: ['id', 'title', 'status', 'created_at'],
  sort: [
    { status: { direction: 'asc' } },
    { created_at: { direction: 'desc' } },
  ],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,status,created_at&sort[0][status][direction]=asc&sort[1][created_at][direction]=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams();
params.set('fields', 'id,title,status,created_at');
params.set('sort[0][status][direction]', 'asc');
params.set('sort[1][created_at][direction]', 'desc');

const response = await fetch(
  `https://example.monospace.io/api/blog/items/articles?${params}`,
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

Sort specifiers apply in order — the second field only breaks ties in the first.

Paginate with Limit and Offset

Use limit to control how many items are returned and offset to skip items. The default limit is 100, configurable via DIRECTUS_QUERY_LIMIT_DEFAULT. The maximum allowed limit is set by DIRECTUS_QUERY_LIMIT_MAX. Set limit=0 or limit=-1 to request unlimited results (subject to the configured maximum).

Return the first 10 articles:

const articles = await client.Articles.readMany({
  fields: ['id', 'title'],
  limit: 10,
  offset: 0,
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title&limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  fields: 'id,title',
  limit: '10',
  offset: '0',
});

const response = await fetch(
  `https://example.monospace.io/api/blog/items/articles?${params}`,
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

Return the second page (items 11-20):

const articles = await client.Articles.readMany({
  fields: ['id', 'title'],
  limit: 10,
  offset: 10,
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title&limit=10&offset=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  fields: 'id,title',
  limit: '10',
  offset: '10',
});

const response = await fetch(
  `https://example.monospace.io/api/blog/items/articles?${params}`,
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

Implement Page-Based Navigation

Calculate the offset from a page number using offset = (page - 1) * pageSize. There is no page or meta query parameter — pagination is strictly limit/offset-based.

Fetch page 3 with 25 items per page:

const page = 3;
const pageSize = 25;
const offset = (page - 1) * pageSize;

const articles = await client.Articles.readMany({
  fields: ['id', 'title', 'status'],
  limit: pageSize,
  offset,
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,status&limit=25&offset=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

const page = 3;
const pageSize = 25;
const offset = (page - 1) * pageSize;

const params = new URLSearchParams({
  fields: 'id,title,status',
  limit: String(pageSize),
  offset: String(offset),
});

const response = await fetch(
  `https://example.monospace.io/api/blog/items/articles?${params}`,
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

The SDK unwraps the { data } envelope by default. See Client Setup.

Offset-based pagination can skip or duplicate items if data changes between requests. Sort by a stable, unique field like id for consistent results.

Page-based and cursor-based pagination are not currently supported. These are planned for future versions. For now, all pagination is done with limit and offset.

Sort and Paginate Within Nested Relations

Apply sorting and pagination to related collections using expanded field selection. In REST, use deep with underscore-prefixed keys. In the SDK, use sort, limit, and offset inside the expanded relation object.

Return each article with its 5 most recent comments:

const articles = await client.Articles.readMany({
  fields: ['id', 'title', {
    comments: {
      fields: ['id', 'body', 'created_at'],
      sort: [{ created_at: { direction: 'desc' } }],
      limit: 5,
    },
  }],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,comments.id,comments.body,comments.created_at&deep[comments][_sort][0][created_at][direction]=desc&deep[comments][_limit]=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/articles');
url.searchParams.set('fields', 'id,title,comments.id,comments.body,comments.created_at');
url.searchParams.set('deep[comments][_sort][0][created_at][direction]', 'desc');
url.searchParams.set('deep[comments][_limit]', '5');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

const { data } = await response.json();

For more on selecting nested fields and the expanded field selection syntax, see Field Selection.