# One indicator as a clean time series

getSeries · GET /api/series/{series_id}

## Endpoint
`GET /api/series/{series_id}`

One row per period, oldest first, with previous_value. origin=archive is a release we watched appear (release_date, revised); origin=backfill is older history from the published CSVs (provenance). Where both exist and disagree, both values are published (archive_value, backfill_value) and backfill_disagrees is true; a monthly or policy release keeps the archive, a daily quote takes the publisher-dated backfill, and an archive monthly row first seen before its month ended is rejected (archive_rejected). The tier history window bounds the earliest period (x-api-tiers): Pro reads the full series, e.g. CPI YoY from 2008-01. Over the tier row ceiling the newest rows are kept and truncated is true.

## Authentication
```json
[]
```
An empty security requirement means this operation does not declare authentication. Read operation notes for entitlement and protocol-method requirements.

## Parameters
| Name | In | Required | Description |
| --- | --- | --- | --- |
| series_id | path | Yes | From /api/series, e.g. cpi-yoy. |
| from | query | No | Earliest reference period, YYYY-MM or YYYY-MM-DD. |
| to | query | No | Latest reference period, inclusive. |
| format | query | No | CSV returns the same observations as UTF-8 with BOM. |

## Responses and errors
| HTTP status | Meaning |
| --- | --- |
| 200 | The series. |
| 400 | Invalid series_id, period or format. |
| 404 | Unknown series, or no observations in the caller history window. |
| 429 | Rate limit exceeded. |
| 503 | Archive unavailable; retry later. |

## Response examples
No response example is supplied by OpenAPI for this operation. The complete response schemas are preserved below; use an actual response for observed values.

## Retry guidance
See [errors and retries](/docs/api/overview#errors-and-retries). Honor operation-specific response headers. A POST may create state; do not replay it automatically.

## Complete operation contract
The expanded contract below includes all parameter constraints, response headers, schemas and examples from OpenAPI.

```json
{
  "path": "/api/series/{series_id}",
  "method": "GET",
  "parameters": [
    {
      "name": "series_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
      },
      "description": "From /api/series, e.g. cpi-yoy."
    },
    {
      "name": "from",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
      },
      "description": "Earliest reference period, YYYY-MM or YYYY-MM-DD."
    },
    {
      "name": "to",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
      },
      "description": "Latest reference period, inclusive."
    },
    {
      "name": "format",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "csv"
        ],
        "default": "json"
      },
      "description": "CSV returns the same observations as UTF-8 with BOM."
    }
  ],
  "operationId": "getSeries",
  "summary": "One indicator as a clean time series",
  "description": "One row per period, oldest first, with previous_value. origin=archive is a release we watched appear (release_date, revised); origin=backfill is older history from the published CSVs (provenance). Where both exist and disagree, both values are published (archive_value, backfill_value) and backfill_disagrees is true; a monthly or policy release keeps the archive, a daily quote takes the publisher-dated backfill, and an archive monthly row first seen before its month ended is rejected (archive_rejected). The tier history window bounds the earliest period (x-api-tiers): Pro reads the full series, e.g. CPI YoY from 2008-01. Over the tier row ceiling the newest rows are kept and truncated is true.",
  "tags": [
    "data",
    "Inspect observations",
    "Export"
  ],
  "security": [],
  "responses": {
    "200": {
      "description": "The series.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "series_id",
              "observations",
              "truncated"
            ]
          }
        },
        "text/csv": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "400": {
      "description": "Invalid series_id, period or format."
    },
    "404": {
      "description": "Unknown series, or no observations in the caller history window."
    },
    "429": {
      "description": "Rate limit exceeded."
    },
    "503": {
      "description": "Archive unavailable; retry later."
    }
  },
  "x-codeSamples": [
    {
      "lang": "curl",
      "label": "curl",
      "source": "curl -s 'https://china-snapshot.com/api/series/pmi-manufacturing'"
    },
    {
      "lang": "curl",
      "label": "curl",
      "source": "curl -s -o pmi.csv 'https://china-snapshot.com/api/series/pmi-manufacturing?from=2025-01&format=csv'"
    }
  ]
}
```