Skip to main content

Query Parameters

Our API provides a flexible way to retrieve data through query parameters. This guide explains the available query parameters and how to use them effectively.

Endpoints​

Query parameters are available on the following endpoints:

  • GET /api/v1/environments
  • GET /api/v1/environments/{environmentID}/nodes
  • GET /api/v1/workspaces/{workspaceID}/nodes
  • GET /api/v1/runs
  • GET /api/v1/runs/{runID}
Varies By Endpoint

Review each endpoint for available parameters.

What Is Cursor-Based Pagination?​

Cursor-based pagination is like using a bookmark in a large dataset. Instead of asking for a specific page number, you are asking to "show me results that come after this point."

Our endpoints offer this using startingFrom.

Title example

When using startingFrom, you must also include the orderBy parameter to define the sort order used for the cursor.

Example of Cursor-Based Pagination​

Imagine you have a collection of 500 Nodes in the database, and you want to retrieve 10 Nodes at a time:

Get First 10 Nodes Request​

GET /api/v1/environments/{environmentID}/nodes?limit=10&orderBy=id

Get First 10 Nodes Response​

You get 10 Nodes and a cursor value in the next field, which points to where you left off.

{
  "data": [
    {
      "database": "sales",
      "id": "27",
      "locationName": "US-East",
      "name": "Region",
      "nodeType": "Dimension",
      "schema": "public"
    }
  ],
  "total": 500,
  "limit": 10,
  "next": "eyJpZCI6IjMzIn0",
  "orderBy": "id"
}

Get Next 10 Nodes Request​

Use the next value in the startingFrom parameter and include the same orderBy.

GET /api/v1/environments/{environmentID}/nodes?limit=10&startingFrom=eyJpZCI6IjMzIn0&orderBy=id

Get Next 10 Nodes Response​

{
  "data": [
    {
      "database": "sales",
      "id": "39",
      "locationName": "US-West",
      "name": "Territory",
      "nodeType": "Dimension",
      "schema": "public"
    }
  ],
  "total": 500,
  "startingFrom": "eyJpZCI6IjMzIn0",
  "limit": 10,
  "next": "eyJpZCI6IjE3OCJ9",
  "orderBy": "id"
}

Using the next Field​

When paginating, the next value in the response allows you to fetch the next set of results. To do this:

  1. Copy the next value from the response.
  2. Pass it as the startingFrom value in your next request.
  3. Always include the same orderBy value used in the previous request.

Query Parameter Example​

Here are a few examples of using query parameters.

Using limit, startingFrom, and orderBy​

These examples use the Workspace endpoint to demonstrate paginated requests.

Get the first 25 Nodes

GET /api/v1/workspaces/{workspaceID}/nodes?limit=25&orderBy=id

Response with next

{
  "data": [ /* 25 Nodes */ ],
  "total": 142,
  "limit": 25,
  "next": "eyJpZCI6IjEyOCJ9",
  "orderBy": "id"
}

Get the next 25 Nodes

GET /api/v1/workspaces/{workspaceID}/nodes?limit=25&startingFrom=eyJpZCI6IjEyOCJ9&orderBy=id

Using orderBy with Sort Direction​

This returns runs sorted by runStartTime from most recent to oldest.

GET /api/v1/runs?orderBy=runStartTime&orderByDirection=desc

When next Is Null​

If "next": null, you've reached the end of the dataset.

{
  "data": [],
  "total": 0,
  "startingFrom": "eyJpZCI6IjEyOCJ9",
  "limit": 2,
  "next": null,
  "orderBy": "id"
}