> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deep Query

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

[Deep Query](/optimize/deep-query) reads the records [Data Sync](/optimize/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](/embed/call-actions/rpc-http) call. No provider request is made.

```bash theme={null}
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": "bamboohr_list_employees",
        "filter": { "term": { "department": "Engineering" } },
        "source": ["first_name", "email"],
        "sort": [{ "last_name": "desc" }],
        "page_size": 50
      }'
```

The request takes `filter` and `search` to narrow the record set, `sort` and `source` to shape what comes back, `aggs` to return numbers instead of records, and `page_size` with `skip` to page. The [API reference](/platform/api-reference/actions/read-synced-action-data-from-the-datasync-index) 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 in the provider's own shape, with the provider's field names and nesting - not the normalized shape a regular action call returns. Filter and sort against those names.

<Note>
  No API endpoint lists the queryable field names. Run a query with no `filter` and read them off the records, or open **Actions Request Tester** in the dashboard and pick the `(S1Query)` entry for the action. Agents calling through [MCP](/embed/call-actions/mcp) get a `list_s1query_queryable_fields` tool instead.
</Note>

## Aggregate instead of paging

An aggregation answers a question about the whole record set without returning the records:

```bash theme={null}
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": "bamboohr_list_employees",
        "aggs": { "by_department": { "terms": { "field": "department" } } }
      }'
```

That returns one bucket per department with a count in each. Setting `aggs` returns aggregations instead of records, so `source`, `sort`, `page_size`, and `skip` are ignored, but `filter` still applies and lets you aggregate over a subset. The [API reference](/platform/api-reference/actions/read-synced-action-data-from-the-datasync-index) 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.

<Note>
  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.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Deep Query" icon="magnifying-glass-chart" href="/optimize/deep-query">
    What it does, when to reach for it, and how an agent uses it.
  </Card>

  <Card title="Data Sync" icon="rotate" href="/optimize/data-sync">
    Turn on the sync this reads from, and set how often it refreshes.
  </Card>

  <Card title="RPC/HTTP" icon="terminal" href="/embed/call-actions/rpc-http">
    Call an action live against the provider instead.
  </Card>

  <Card title="API reference" icon="code" href="/platform/api-reference/actions/read-synced-action-data-from-the-datasync-index">
    The `/actions/rpc/synced` endpoint.
  </Card>
</CardGroup>