Deep Query

Read synced provider records over the API, with filters, full-text search, and aggregations.

Deep Query reads the records Data Sync has stored, without calling the provider. Sync has to be on for the action first, which is configured per action on a Connector Profile in the dashboard.

Query synced records

Call POST /actions/rpc/synced with the action and the account header, authenticating the same way as any RPC/HTTP call. No provider request is made.

For example, reading the names and job titles of active BambooHR employees, sorted by last name:

cURL

curl -X POST "https://api.stackone.com/actions/rpc/synced?page_size=50" \
  -u "$STACKONE_API_KEY:" \
  -H "x-account-id: <ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
        "action": "bamboohr_list_employees",
        "filter": { "term": { "status": "Active" } },
        "source": ["firstName", "lastName", "jobTitleName"],
        "sort": [{ "lastName": "asc" }]
      }'

The body takes filter and search to narrow the record set, sort and source to shape what comes back, and aggs to return numbers. page_size and skip are query parameters. The API reference gives each one’s accepted shape.

If an account has more than one sync for the same action, pass sync_id to choose which one to read.

Records come back as the provider returned them to Data Sync, with the provider’s field names and nesting, which can differ from the live action’s result. Filter and sort against those names, as listed by the queryable fields.

Page through records

Set the page_size (up to 200, default 100) and skip query parameters to page. skip plus page_size can’t go past 10,000, so narrow the filter to reach records beyond that. A page of large records can hold fewer records than page_size, so the response stays under its size limit. That page has "truncated": true. Get the next page from skip plus the number of records returned, not skip plus page_size.

If a single record is too large to fit in a page, the request fails with a 400 that names source. Pass a source with fewer fields to read it.

List the queryable fields

Call POST /actions/rpc/synced/queryable_fields with the action and the same account header to get the fields you can filter, sort, and aggregate on, with their types. Listing fields isn’t billed. For example:

cURL

curl -X POST "https://api.stackone.com/actions/rpc/synced/queryable_fields" \
  -u "$STACKONE_API_KEY:" \
  -H "x-account-id: <ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "bamboohr_list_employees" }'

The response lists each field with its index type, such as keyword or date, and the syncs the fields come from. fields is empty when the action has nothing synced for the account yet. Agents calling through MCP get the same list from the list_s1query_queryable_fields tool.

Fields nested five or more levels deep, and lists of lists, aren’t indexed, so they’re missing from this list. Records still return them, up to the 64 KB per-record limit. Naming one in filter, sort, or aggs returns a 400. A field five or more levels deep can still be named in source, and the response then includes the whole nested object it belongs to. See Deeply nested data for how depth is counted.

Aggregate instead of paging

An aggregation answers a question about the whole record set without returning the records. For example, counting Zendesk tickets by status:

cURL

curl -X POST "https://api.stackone.com/actions/rpc/synced" \
  -u "$STACKONE_API_KEY:" \
  -H "x-account-id: <ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
        "action": "zendesk_list_tickets",
        "aggs": { "by_status": { "terms": { "field": "status" } } }
      }'

That returns one bucket per ticket status under aggregations, with a count in each. filter and search still apply, so you can aggregate over a subset. Without page_size, the response holds only the aggregations, and source and sort are ignored. skip has no effect there but is still checked against its limit. Set page_size to get a page of the matching records in data from the same request. The API reference lists the supported bucket and metric aggregations and how deeply they nest.

Response metadata

Every response carries a datasync block describing how fresh the data you just read is: when the readable records were written, when they expire if no further run happens, and the runs that produced them.

Querying an action that has nothing synced yet returns 200 with synced: false and a message, not an error. Treat it as a signal to fall back to a live action call.

Next steps

Deep Query

What it does, when to reach for it, and how an agent uses it.

Data Sync

Turn on the sync this reads from, and set how often it refreshes.

RPC/HTTP

Call an action live against the provider instead.

API reference

The /actions/rpc/synced endpoint.