Hodoflow / Developers
Sign in
Browse documentation
Help Center →
Browse API reference
GraphQL 2026-07-05 stable

Query warehouse facts

Read the latest row per entity or a bounded historical timeline for one data model. The schema exposes no mutations or subscriptions.

POST /api/graphql

Access and behavior

Required scope
api_read
Authentication
Bearer token (health is the only public field)
Idempotency
not-applicable; factQuery is read-only
Operation ID
factQuery

Request headers

Header Presence Description
Authorization Required Short-lived service-account token.
Content-Type Required GraphQL JSON request envelope.

Parameters

dataModelSlug

argument · Required

String!

Data-model slug resolved in the service account's workspace.

mode

argument · Optional

String

latest returns one current row per entity; timeline returns history.

Default: latest

timeAxis

argument · Optional

String

Choose observed_at or inserted_at for time-window filtering.

Default: observed_at

since

argument · Optional

DateTime

Inclusive lower time-window bound.

until

argument · Optional

DateTime

Upper time-window bound; defaults to now for timeline mode.

filters

argument · Optional

String

JSON array encoded as a GraphQL string; at most 20 filters.

sort

argument · Optional

String

Timeline sort field: observed_at, inserted_at, or entity_id.

Default: observed_at

sortDirection

argument · Optional

String

Timeline order: asc or desc.

Default: desc

limit

argument · Optional

Int

Rows per page; maximum 250 and also bounded by query complexity.

Default: 50

offset

argument · Optional

Int

Number of matching rows to skip.

Default: 0

Request body

application/json

Schema: GraphQLRequest · Required

request.json 
{
  "query": "query CurrentFacts($slug: String!, $limit: Int!) {\n  factQuery(dataModelSlug: $slug, mode: \"latest\", limit: $limit) {\n    count\n    hasNextPage\n    results { entityId observedAt data }\n  }\n}",
  "variables": {
    "limit": 25,
    "slug": "order"
  }
}

Success response

200 A bounded PageOfFact result.
Media type
application/json
Schema
PageOfFact

Errors and retries

Keep x-request-id from failed responses. Retry only rows marked retryable, and obey Retry-After when present.

Status Code Recovery Meaning
401 unauthorized Do not retry unchanged The bearer token is invalid or revoked.
403 forbidden Do not retry unchanged factQuery requires api_read and an active run-as member.
200 graphql_validation Do not retry unchanged The query, variables, slug, filter, or limit is invalid.
200 query_too_complex Do not retry unchanged Complexity exceeds 200, depth exceeds 10, or the document exceeds 8,000 tokens.
429 rate_limited Retry after guidance Wait for Retry-After before sending another request.

Related guides

Run your first warehouse query Obtain a real data-model slug, send a bounded factQuery with variables, and verify empty or populated GraphQL results. GraphQL filters, pagination, and limits Encode factQuery filters safely, page with explicit limits and offsets, and stay within time-window, complexity, depth, and token guards.