ExanomicDocs
OverviewAuthenticationEnvironments
OverviewInflationLabor MarketInterest RatesGDP & OutputSeries EndpointsObservationsTreasury APICorrelation API
ExanomicDocs
GET/v2/series/{id}/observations

Get Time Series Observations

Retrieve historical time series data for a specific series.

Fetch time series observations (data points) for a given series. This is the core endpoint for accessing actual economic data values. You can filter by date range, limit results, and specify the output format. Observations are returned in chronological order.

Authentication: Your API key is required to access time series data.

Parameters

NameTypeRequiredDescription
idstringRequiredThe unique identifier of the series.
id
stringRequired

The unique identifier of the series.

Query Parameters

NameTypeRequiredDescription
startDatestringOptionalStart date for observations (ISO 8601 format: YYYY-MM-DD).
endDatestringOptionalEnd date for observations (ISO 8601 format: YYYY-MM-DD).
limit
default: 1000
integerOptionalMaximum number of observations to return (max 10000).
offset
default: 0
integerOptionalNumber of observations to skip (for pagination).
sort
default: asc
stringOptionalSort order: "asc" (oldest first) or "desc" (newest first).
transform
default: none
stringOptionalData transformation: "none", "diff" (first difference), "pct_change" (percent change).
startDate
stringOptional

Start date for observations (ISO 8601 format: YYYY-MM-DD).

endDate
stringOptional

End date for observations (ISO 8601 format: YYYY-MM-DD).

limit
default: 1000
integerOptional

Maximum number of observations to return (max 10000).

offset
default: 0
integerOptional

Number of observations to skip (for pagination).

sort
default: asc
stringOptional

Sort order: "asc" (oldest first) or "desc" (newest first).

transform
default: none
stringOptional

Data transformation: "none", "diff" (first difference), "pct_change" (percent change).

Response Attributes

NameTypeRequiredDescription
seriesId
stringRequiredThe series identifier.
observations
arrayRequiredArray of observation objects.
—date
stringRequiredISO 8601 date of the observation.
—value
numberRequiredThe observed value.
metadata
objectRequiredMetadata about the returned data.
—count
integerRequiredNumber of observations returned.
—startDate
stringRequiredEarliest date in the response.
—endDate
stringRequiredLatest date in the response.
seriesId
stringRequired

The series identifier.

observations
arrayRequired

Array of observation objects.

date
stringRequired

ISO 8601 date of the observation.

value
numberRequired

The observed value.

metadata
objectRequired

Metadata about the returned data.

count
integerRequired

Number of observations returned.

startDate
stringRequired

Earliest date in the response.

endDate
stringRequired

Latest date in the response.

Error Responses

400Bad request. Invalid parameters.
{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid date format. Use YYYY-MM-DD"
  }
}
404Series not found.
{
  "error": {
    "code": "not_found",
    "message": "Series with ID \"INVALID\" not found"
  }
}
401Unauthorized. Invalid or missing Bearer token.
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing Bearer token"
  }
}

Notes

  • Observations are returned in chronological order by default. Use sort=desc to reverse the order.
  • The maximum number of observations per request is 10,000. Use offset and limit for pagination.
  • Use ISO 8601 dates (YYYY-MM-DD) for startDate and endDate.
  • Use transform for first differences or percent changes in time series analysis.

API Method

GET /v2/series/{id}/observations

Example Usage

curl -X GET "https://api.exanomic.com/v2/series/UNRATE/observations?startDate=2020-01-01&endDate=2024-12-01&limit=100" \
  -H "X-API-Key: your-api-key-here"

Example Response

{
  "seriesId": "UNRATE",
  "observations": [
    {
      "date": "2024-01-01",
      "value": 3.7
    },
    {
      "date": "2024-02-01",
      "value": 3.8
    },
    {
      "date": "2024-03-01",
      "value": 3.9
    },
    {
      "date": "2024-04-01",
      "value": 3.8
    },
    {
      "date": "2024-05-01",
      "value": 3.7
    }
  ],
  "metadata": {
    "count": 5,
    "startDate": "2024-01-01",
    "endDate": "2024-05-01"
  }
}