Athena
Fetch

Fetch data with conditions

Fetches rows from a table or view using structured conditions, optional pagination, sort instructions, and optional post-processing (`group_by`, `time_granularity`, aggregation options). Notes: - Route selection is based on `X-Athena-Client` (or custom Supabase headers for `custom_supabase`). - `X-Strip-Nulls` can be used to remove null-valued fields from response payloads. - Cache behavior may include `X-Athena-Cached`, `X-Athena-Cache-Outcome`, and `X-Athena-Cache-Source` headers.

POST
/gateway/fetch

Header Parameters

X-User-Id?string
X-Athena-Client?string
X-Strip-Nulls?string
apikey?string
x-api-key?string

optional API key mirror of the apikey header

x-supabase-url?string

Required when X-Athena-Client is custom_supabase

Formaturi
x-supabase-key?string

Required when X-Athena-Client is custom_supabase

Request Body

application/json

view_name?string
table_name?string
columns?array<>|
conditions*array<>
limit?integer
current_page?integer
page_size?integer
offset?integer
total_pages?integer
strip_nulls?boolean
group_by?string

Column name to group results by

time_granularity?string

Time granularity for grouping timestamp data

Value in"day" | "hour" | "minute"
aggregation_column?string

Column to aggregate (required when using aggregation_strategy)

aggregation_strategy?string

Aggregation strategy to apply (requires aggregation_column)

Value in"cumulative_sum"
aggregation_dedup?boolean

Whether to deduplicate during aggregation

sortBy?

Optional sort (camelCase). Use sort_by for snake_case.

sort_by?

Optional sort (snake_case). Same shape as sortBy.

Response Body

application/json

curl -X POST "https://athena-cluster.com/gateway/fetch" \  -H "Content-Type: application/json" \  -d '{    "table_name": "http_request_log",    "columns": [      "id",      "path",      "status_code",      "created_at"    ],    "conditions": [      {        "eq_column": "client_name",        "eq_value": "athena_logging"      }    ],    "limit": 25,    "current_page": 1,    "sortBy": {      "field": "created_at",      "direction": "desc"    }  }'
{
  "status": "success",
  "message": "Fetched 25 rows",
  "data": {
    "rows": [
      {
        "id": "5d845b27-8d06-40a0-9e76-08de9d9f3c1f",
        "path": "/gateway/fetch",
        "status_code": 200,
        "created_at": "2026-04-14T10:15:00Z"
      }
    ],
    "row_count": 25
  }
}
Empty
Empty