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

# GET /v1/questions

> List multi-outcome question groupings (pending upstream).

<Note>
  **Feature status: `pending_upstream`.** Hyperliquid does not currently emit question metadata on-chain. Until HL ships question records the index has nothing to populate this endpoint with. The route is wired and stable — it will start returning data automatically once HL emits it. No client changes will be needed.
</Note>

HIP-4 outcomes can in principle be grouped into multi-outcome **questions** (e.g. "Who wins NFL MVP" with one outcome per candidate). This endpoint will surface that grouping when it exists. For now use `/v1/markets` to enumerate individual outcomes.

## Endpoint

```
GET /v1/questions
GET /v1/questions/:qid
```

## Response (current — feature pending)

```json theme={null}
{
  "count": 0,
  "questions": [],
  "note": "HIP-4 question metadata (parent grouping linking related outcomes) is not yet emitted on-chain by Hyperliquid. This endpoint will populate automatically once HL ships question records. Use /v1/markets to enumerate individual outcomes in the meantime.",
  "feature_status": "pending_upstream"
}
```

## Response (future — when HL ships questions)

```json theme={null}
{
  "count": 1,
  "questions": [
    {
      "question_id": 7,
      "name": "SuperBowl2027",
      "description": "Which team wins Super Bowl LXI",
      "outcome_ids": [10, 11, 12, 13],
      "outcome_count": 4,
      "fallback_outcome": null,
      "deployed_at": { "us": 1777..., "iso": "...", "relative": "..." }
    }
  ]
}
```

## /v1/questions/:qid

Returns one question's metadata. Until HL emits questions this returns:

```
HTTP 404
{
  "error": "question N not found",
  "note": "HIP-4 question metadata is not yet emitted on-chain by Hyperliquid. No questions exist in this index yet. Endpoint will work automatically once HL ships question records.",
  "feature_status": "pending_upstream"
}
```

## How to know when this goes live

Poll `/v1/questions` (cheap — single Postgres scan against an empty table). When `count > 0`, HL has shipped questions and the data is live. The `feature_status` and `note` fields will disappear from the response once data exists.

For aggregating data across the outcomes belonging to one question (sum-of-probabilities, top holders across the whole event), see [`/v1/questions/:qid/aggregate`](/questions/aggregate).