Shape your requests

Pagination, filtering, sorting, and field selection work the same on every MindCloud API list endpoint.

Every list endpoint supports the same query grammar. Learn it once and it applies to workflows, runs, connections, and everything else.

Pagination

Use limit and offset. limit defaults to 100 and caps at 1000. The response meta includes the total count:

curl "https://connect.mindcloud.co/v2/workflows/wf_8f2k1/runs?limit=50&offset=100" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Every list has a stable default order, so pages stay consistent without passing sort.

Sorting

Pass sort with one or more comma-separated fields. Prefix a field with - for descending:

curl "https://connect.mindcloud.co/v2/workflows/wf_8f2k1/runs?sort=-startedOn" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Field selection

Pass fields to receive only the columns you need:

curl "https://connect.mindcloud.co/v2/workflows?fields=id,name,isActive" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Filtering

Any exposed field filters with plain equality or a bracket operator:

# Equality
curl "https://connect.mindcloud.co/v2/workflows/wf_8f2k1/runs?status=failed" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

# Operators
curl "https://connect.mindcloud.co/v2/workflows/wf_8f2k1/runs?startedOn[gte]=2026-07-01&status[in]=failed,interrupted" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Operator	Meaning
`eq`	Equals (same as no operator)
`ne`	Not equal
`gt`, `gte`	Greater than, greater or equal
`lt`, `lte`	Less than, less or equal
`contains`	Substring match
`starts`, `ends`	Prefix or suffix match
`in`, `nin`	In or not in a comma-separated list

Rate limits

Each API key gets 240 read requests (GET) and 60 write requests (POST, PUT, DELETE) per minute, in separate budgets. Every response reports where you stand:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute for this budget
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets

Past the limit, requests return 429 with code RATE_LIMITED and a Retry-After header with the seconds to wait. Back off until then; the budget refills at the reset time.

Errors

Invalid parameters return 400 with code INVALID_QUERY. Missing resources return 404 with code NOT_FOUND. A key without the access level an endpoint needs returns 403 with code API_KEY_ACCESS_DENIED. A write that conflicts with the resource's state returns 409 with a specific code, like WORKFLOW_NOT_PUBLISHED when you run a workflow that was never published, or CONNECTION_IN_USE when active workflows still use a connection you asked to delete. The envelope is always:

{
  "success": false,
  "error": { "code": "INVALID_QUERY", "message": "Invalid filter \"startedOn[foo]\"" }
}