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

# List topics

> Query and list research topic clusters with filtering, sorting, and pagination.

Retrieves a paginated list of research topics with filtering and sorting capabilities.

### Query Parameters

<ParamField query="page" default="1" type="integer">
  Page number for pagination. Default is `1`.
</ParamField>

<ParamField query="per_page" default="25" type="integer">
  Results per page. Allowed values: `10`, `25`, `50`, `100`.
</ParamField>

<ParamField query="filter" type="string">
  Filter expression (e.g. `domain.id:3`).
</ParamField>

<ParamField query="sort" type="string">
  Sorting parameter (e.g. `outputs_count:desc`, `cited_by_count:desc`).
</ParamField>

### Response Fields

<ResponseField name="meta" type="object" required>
  Pagination metadata.

  <Expandable title="meta attributes">
    <ResponseField name="count" type="integer">Total matching records count.</ResponseField>
    <ResponseField name="page" type="integer">Current page number.</ResponseField>
    <ResponseField name="per_page" type="integer">Items per page.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="results" type="array" required>
  Array of topic records.

  <Expandable title="results item attributes">
    <ResponseField name="id" type="string">Topic ID (`HX_T...`).</ResponseField>
    <ResponseField name="name" type="string">Topic display name.</ResponseField>
    <ResponseField name="description" type="string">Scope description.</ResponseField>
    <ResponseField name="keywords" type="array">Associated keyword strings array.</ResponseField>

    <ResponseField name="ids" type="object">
      External identifiers.

      <Expandable title="ids attributes">
        <ResponseField name="wikipedia" type="string">Wikipedia URL.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="subfield" type="object">
      Parent subfield.

      <Expandable title="subfield attributes">
        <ResponseField name="id" type="string">Subfield numeric ID.</ResponseField>
        <ResponseField name="name" type="string">Subfield display name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="field" type="object">
      Parent field.

      <Expandable title="field attributes">
        <ResponseField name="id" type="string">Field numeric ID.</ResponseField>
        <ResponseField name="name" type="string">Field display name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="domain" type="object">
      Parent domain.

      <Expandable title="domain attributes">
        <ResponseField name="id" type="string">Domain numeric ID.</ResponseField>
        <ResponseField name="name" type="string">Domain display name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="siblings" type="array">
      Sibling topic clusters.

      <Expandable title="siblings attributes">
        <ResponseField name="id" type="string">Sibling topic ID (`HX_T...`).</ResponseField>
        <ResponseField name="name" type="string">Sibling topic display name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="outputs_count" type="integer">Outputs count.</ResponseField>
    <ResponseField name="cited_by_count" type="integer">Citations count.</ResponseField>
    <ResponseField name="updated_date" type="string">Last updated timestamp.</ResponseField>
    <ResponseField name="created_date" type="string">Creation timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.hexagraph.in/topics?sort=outputs_count:desc&per_page=10"
  ```

  ```javascript JavaScript theme={null}
  fetch("https://api.hexagraph.in/topics?sort=outputs_count:desc&per_page=10")
    .then(response => response.json())
    .then(data => console.log(data));
  ```

  ```python Python theme={null}
  import requests

  response = requests.get("https://api.hexagraph.in/topics", params={"sort": "outputs_count:desc", "per_page": 10})
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "meta": {
      "count": 4516,
      "page": 1,
      "per_page": 25
    },
    "results": [
      {
        "id": "HX_T14423",
        "name": "Military Technology and Strategies",
        "description": "This cluster of papers covers various aspects related to the modernization and development of air force capabilities, including the use of unmanned aerial vehicles, radar systems, military communication, electronic components, and strategic planning. It also explores the intersection of strategic planning, foresight, and design in the context of air force modernization.",
        "keywords": [
          "Air Force",
          "Modernization",
          "Warfare",
          "Unmanned Aerial Vehicles",
          "Radar Systems",
          "Military Communication",
          "Electronic Components",
          "Strategic Planning",
          "Foresight",
          "Design"
        ],
        "ids": {
          "wikipedia": "https://en.wikipedia.org/wiki/Air_force_modernization"
        },
        "subfield": {
          "id": "2202",
          "name": "Aerospace Engineering"
        },
        "field": {
          "id": "22",
          "name": "Engineering"
        },
        "domain": {
          "id": "3",
          "name": "Physical Sciences"
        },
        "siblings": [
          {
            "id": "HX_T10069",
            "name": "Antenna Design and Analysis"
          },
        ],
        "outputs_count": 22344034,
        "cited_by_count": 843046,
        "updated_date": "2026-08-05T03:01:31",
        "created_date": "2024-01-23T15:27:22"
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "statusCode": 400,
    "message": "Bad Request - Invalid query parameters",
    "error": "Bad Request"
  }
  ```

  ```json 429 Rate Limit Exceeded theme={null}
  {
    "statusCode": 429,
    "message": "Rate limit exceeded. Maximum 30 requests per minute.",
    "error": "Too Many Requests"
  }
  ```
</ResponseExample>