# Get a Topic measurement series

`GET /v3/topics/{topicId}/series/{measure}`

The same measurement-series contract used by Projects, for one known
Topic id. `trend` keeps the newest real completed score boundary in
each hourly bucket. `rank` is the committed Trend-boundary series reduced to change points;
`value` is `null` when a complete leaderboard publishes the Topic as
unranked. Point timestamps preserve the actual completed measurement
boundary. Topic history requires an API key.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "name": "topicId",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "pattern": "^topic_[a-f0-9]{20}$"
    }
  },
  {
    "name": "measure",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "enum": [
        "trend",
        "rank"
      ]
    }
  },
  {
    "name": "from",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "to",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Series page.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "object",
              "required": [
                "topic",
                "points"
              ],
              "properties": {
                "topic": {
                  "$ref": "#/components/schemas/TopicRef"
                },
                "points": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SeriesPoint"
                  }
                }
              }
            },
            "meta": {
              "$ref": "#/components/schemas/SeriesMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Hourly Topic trend series",
            "value": {
              "data": {
                "topic": {
                  "id": "topic_a1b2c3d4e5f601234567",
                  "name": "Restaking yield compression"
                },
                "points": [
                  {
                    "at": "2026-08-05T03:45:00Z",
                    "value": 91.8
                  },
                  {
                    "at": "2026-08-05T04:45:00Z",
                    "value": 93.2
                  }
                ]
              },
              "meta": {
                "measure": "trend",
                "basis": "hourly",
                "window": {
                  "from": "2026-08-04T05:00:00Z",
                  "to": "2026-08-05T05:00:00Z"
                },
                "versions": {
                  "trendModel": "trend-nb-predictive-v2",
                  "topicAlgorithm": "trend-nb-predictive-v2.topic-relevance-v3"
                },
                "history": {
                  "lookbackDays": 90,
                  "earliestAvailableAt": "2026-05-07T00:00:00Z"
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  },
  "503": {
    "$ref": "#/components/responses/Unavailable"
  }
}
```

## Referenced schemas

```json
{
  "TopicRef": {
    "type": "object",
    "required": [
      "id",
      "name"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "SeriesPoint": {
    "type": "object",
    "required": [
      "at",
      "value"
    ],
    "properties": {
      "at": {
        "type": "string",
        "format": "date-time"
      },
      "value": {
        "oneOf": [
          {
            "type": "number"
          },
          {
            "type": "null"
          }
        ],
        "description": "`null` marks a boundary where the subject was unranked or unmeasured."
      },
      "clusters": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "count"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "count": {
              "type": "integer"
            }
          }
        }
      }
    }
  },
  "SeriesMeta": {
    "allOf": [
      {
        "$ref": "#/components/schemas/Meta"
      },
      {
        "type": "object",
        "required": [
          "measure",
          "basis",
          "window"
        ],
        "properties": {
          "measure": {
            "type": "string",
            "enum": [
              "trend",
              "rank"
            ]
          },
          "basis": {
            "type": "string",
            "enum": [
              "hourly",
              "rank_transitions"
            ],
            "description": "How points are spaced: latest real measurement per one-hour bucket, or rank change points."
          },
          "window": {
            "type": "object",
            "required": [
              "from",
              "to"
            ],
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      }
    ]
  },
  "Meta": {
    "type": "object",
    "description": "Response metadata. Empty when nothing applies.",
    "properties": {
      "history": {
        "$ref": "#/components/schemas/HistoryMeta"
      },
      "versions": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "Named component versions that shaped this response."
      }
    }
  },
  "HistoryMeta": {
    "type": "object",
    "description": "The history window applied to this response. Both fields are null when the account has no history limit.",
    "required": [
      "lookbackDays",
      "earliestAvailableAt"
    ],
    "properties": {
      "lookbackDays": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ]
      },
      "earliestAvailableAt": {
        "oneOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ]
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).