---
title: "Find statistical series"
method: POST
path: "/api/v1/find_series"
tags: ["general"]
---

# Find statistical series

`POST /api/v1/find_series`

## Request

- Base URL: `https://scholarmuse.ai`
- URL: `https://scholarmuse.ai/api/v1/find_series`
- Auth: HTTP bearer

Find official statistical series and indicators (GDP, CPI, unemployment, population, life expectancy…) in FRED, World Bank, IMF, OECD, Eurostat, BLS, US Census and Our World in Data. Returns candidates with a seriesId to pass to get_series. Name the country in the query, e.g. "GDP per capita China".

Discipline pack: general. Cost: 2 credits per successful call.

## Request body

- object
  - `query` string, required: What to measure and where, e.g. "US unemployment rate" or "life expectancy Japan".
  - `sources` string[]: Limit to these sources: fred, world-bank, imf, oecd, eurostat, bls, census, owid. Default: all.
  - `limit` integer: Candidates to return (default 10).

## Response `200`

The tool result.

- ToolResult
  - `summary` string, required
  - `billing` CreditStatus
    - `creditsRemaining` integer, nullable, required: Spendable, unexpired balance at checkedAt; null if refresh failed. Credits reserved by pending figures are excluded.
    - `status` 'ok' | 'low' | 'empty' | 'unavailable', required
    - `lowBalanceThreshold` integer, required
    - `topUpUrl` string, uri, required
    - `pricingUrl` string, uri, required
    - `checkedAt` string, date-time, required
    - `notice` string
  - `records` Record[]
    - `id` string, required
    - `type` string, required
    - `source` string, required
    - `title` string
    - `url` string
    - `license` string
    - `attribution` string
    - `retrievedAt` string, date-time, required
    - `data` object, required
  - `partial` boolean
  - `failedSources` object[]
    - `source` string
    - `error` string
  - `files` object[]
    - `name` string
    - `url` string
    - `mimeType` string
  - `extra` object
  - `credits_used` number, required
  - `call_id` string, required

## Other responses

- `400`: The call failed and was not charged.
- `401`: The call failed and was not charged.
- `402`: The call failed and was not charged.
- `429`: The call failed and was not charged.
- `502`: The call failed and was not charged.

---

[API](https://skmtc.dev/scholarmuse/apis/scholarmuse-rest-api.md) · [All operations](https://skmtc.dev/scholarmuse/apis/scholarmuse-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scholarmuse/apis/scholarmuse-rest-api/revisions/beafd92e4bfb?raw)