Instance Search

Stateway's search API lets you query process instances by their variable values and metadata — without fetching them one by one.

Endpoint

POST /v1/instances/search

Authentication: API Key (sw_live_... or sw_test_...). Results are scoped to your tenant automatically — you cannot access another tenant's data regardless of the query.

Use cases

• Operational dashboards: Show all loan-application instances where loan_status = 'in_review' and amount > 50000
• Application logic: Power paginated lists in your backend without a separate query layer
• Compliance investigation: Retrieve instances from a given period where a specific field matches a value

Strong consistency

Stateway reads from the same table the engine writes to. There is no separate index, no sync pipeline, no lag. A variable updated one millisecond ago is visible in the next search call.

Modes

Mode	Trigger	Best for
Structured filter	filter field	Field equality, ranges, existence — index-backed
Full-text search	text.mode: "fulltext"	Keyword search over free-text fields (PT-BR supported)
Fuzzy search	text.mode: "trigram"	Typo-tolerant matching

Structured filters are the most performant. Text and trigram search are explicit opt-ins and incur additional query cost.

Cost

Each call to POST /v1/instances/search costs 1 SOp. See Billing for plan limits.

Via Frontend Gateway

The search() method is also available in the @stateway/frontend-sdk for use in browser frontends. The Gateway applies the searchable_variables visibility policy declared in the session scope — only fields the session is allowed to see appear in filters and results.

const result = await sw.search({
  definitionKey: 'loan-application',
  filter: { 'variables.loan_status': 'in_review' },
  page: { limit: 20 },
});

See SDK Reference for the full method signature, types, and examples. To configure which variables are searchable via the SDK, set searchable_variables in the session scope — see Sessions.