Search Inquiries

POST /api/platform/v1/inquiries/search

Requires inquiries:read. Use search for combined conditions, several statuses, or ordering by the last saved update. Use List Inquiries for simple customer history, and Retrieve an Inquiry for the current state and result of a known task.

Request

curl --request POST 'https://www.uat.gofa.app/api/platform/v1/inquiries/search' \
  --header "Authorization: Bearer $GOFA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": {
      "and": [
        { "attribute": "referenceId", "operator": "eq", "value": "member_7f32a" },
        { "attribute": "workflowId", "operator": "eq", "value": "ai-nutrition" },
        { "or": [
          { "attribute": "status", "operator": "eq", "value": "completed" },
          { "attribute": "status", "operator": "eq", "value": "failed" }
        ] },
        { "attribute": "createdAt", "operator": "gte", "value": "2026-11-01T00:00:00+08:00" },
        { "attribute": "createdAt", "operator": "lt", "value": "2026-12-01T00:00:00+08:00" }
      ]
    },
    "sort": { "attribute": "createdAt", "direction": "desc" },
    "limit": 25
  }'

This finds one customer's November AI Nutrition tasks that completed or failed. The customer reference must come from your authorized user mapping, not an untrusted browser parameter.

All fields belong in the JSON body. URL query parameters and unknown fields are rejected. The maximum body size is 16 KiB. An idempotency key is not required for this read operation.

Conditions

and requires every child to match; or requires at least one; not negates one child. A group has one of those keys only. AND/OR accept 1–10 children. Queries allow up to four nested groups and 40 total nodes, including predicates and groups.

References are trimmed as they are on creation. No substring matching or health result filtering is supported. Timestamps are compared as instants, so equivalent UTC offsets match. updatedAt means the last persisted task update. An effective expired status does not invent a new update timestamp on each search.

Response and pagination

200 OK uses the same summary envelope as List Inquiries:

{
  "ok": true,
  "data": { "items": [], "nextCursor": null },
  "requestId": "example-request-id"
}

Each item omits participant inputs, health results, return URLs, and access tokens. Retrieve an individual Inquiry to read its result.

Keep query and sort unchanged when following nextCursor; changing the page size is allowed. A cursor from another enterprise, filter, sort, or endpoint is rejected. Equal timestamps are ordered by Inquiry ID in the same direction.

A request examines at most 1,000 stored tasks. Sparse matches can therefore return a short or empty page with a non-null nextCursor. Continue until nextCursor is null; do not stop just because items is empty. This is bounded database pagination, not a separate full-text search index.

Search reads stored task data directly without a deliberate indexing delay. Pages are not a frozen snapshot: concurrent updates can move tasks when sorting by updatedAt. Use createdAt for stable historical traversal, deduplicate by Inquiry ID, and use individual retrieval for a current result.

Search uses the enterprise API request rate limit. It neither creates an assessment nor reserves or deducts credits. Authentication, tenant isolation, request IDs, private non-cacheable responses, and error behavior are the same as other read APIs.