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

# Quickstart

> Make your first Financial Data API request and page through results in a few minutes.

This guide takes you from no account to a working request that pulls live macro data, with full provenance, in under five minutes. The base URL is `https://api.financialdatapi.com`, and endpoints use clean, versionless paths such as `/observations/latest`.

## Prerequisites

* A Financial Data API key. Signup is self-serve and free; see [Create an API key](#1-create-an-api-key) below.
* Either `curl` and a shell, or any HTTP client (Python `requests`, Node `fetch`, the official [TypeScript SDK](/sdks/typescript)).
* Node.js 18+ if you plan to use the SDK.

## Get started

<Steps>
  <Step title="Create an API key" icon="key">
    Sign up at [app.financialdatapi.com](https://app.financialdatapi.com), verify your email, and create a key in the dashboard. It works immediately. The Free tier includes 2,500 requests a month with no card required.

    Export the key so the examples below pick it up:

    ```bash theme={"theme":"css-variables"}
    export FINANCIALDATA_API_KEY="your_key_here"
    ```

    <Warning>
      Keys are hashed server-side and never shown again after creation. Store yours securely the moment you create it.
    </Warning>
  </Step>

  <Step title="Make your first request" icon="play">
    Pull the latest US CPI inflation reading. Either header form works; pick one and stay consistent.

    <CodeGroup>
      ```bash cURL theme={"theme":"css-variables"}
      curl "https://api.financialdatapi.com/observations/latest?country=USA&indicator=cpi_inflation_yoy" \
        -H "x-api-key: $FINANCIALDATA_API_KEY"
      ```

      ```python Python theme={"theme":"css-variables"}
      import os, requests

      resp = requests.get(
          "https://api.financialdatapi.com/observations/latest",
          headers={"x-api-key": os.environ["FINANCIALDATA_API_KEY"]},
          params={"country": "USA", "indicator": "cpi_inflation_yoy"},
      )
      resp.raise_for_status()
      print(resp.json()["data"])
      ```

      ```typescript TypeScript theme={"theme":"css-variables"}
      import { FinancialDataApiClient } from "@financialdatapi/client";

      const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

      const { data } = await client.getLatestObservations({
        country: "USA",
        indicator: "cpi_inflation_yoy",
      });
      console.log(data[0].actual, data[0].unit, data[0].period);
      ```
    </CodeGroup>

    You will get back the standard response envelope: the value in `data`, request metadata in `meta`, and a `requestId` for tracing.
  </Step>

  <Step title="Page through a time series" icon="list">
    The latest endpoint returns one row per indicator. To pull history, hit `/observations` and follow the cursor while `meta.pagination.has_more` is `true`.

    <CodeGroup>
      ```python Python theme={"theme":"css-variables"}
      import os, requests

      BASE = "https://api.financialdatapi.com/observations"
      HEADERS = {"x-api-key": os.environ["FINANCIALDATA_API_KEY"]}
      params = {"country": "USA", "indicator": "cpi_inflation_yoy", "limit": 500}

      cursor = None
      while True:
          page = {**params, **({"cursor": cursor} if cursor else {})}
          body = requests.get(BASE, headers=HEADERS, params=page).json()
          for obs in body["data"]:
              print(obs["periodEnd"], obs["actual"])
          pagination = body["meta"]["pagination"]
          if not pagination["has_more"]:
              break
          cursor = pagination["next_cursor"]
      ```

      ```typescript TypeScript theme={"theme":"css-variables"}
      import { FinancialDataApiClient } from "@financialdatapi/client";

      const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

      // The SDK auto-paginates: async iteration follows next_cursor for you.
      for await (const obs of client.paginate("/observations", {
        country: "USA",
        indicator: "cpi_inflation_yoy",
      })) {
        console.log(obs.periodEnd, obs.actual);
      }
      ```
    </CodeGroup>

    See [Pagination](/concepts/pagination) for the full loop.
  </Step>

  <Step title="Trace any value to its source" icon="link">
    Every observation carries `source`, `sourceUrl`, and an `observationId`. Pass the id to the provenance endpoint for the full auditable chain.

    ```bash theme={"theme":"css-variables"}
    curl "https://api.financialdatapi.com/provenance/observations/<observationId>" \
      -H "x-api-key: $FINANCIALDATA_API_KEY"
    ```

    See [Provenance](/concepts/provenance) for what each field means.
  </Step>
</Steps>

## Where to go next

<CardGroup cols={2}>
  <Card title="Authentication & scopes" icon="key" href="/authentication">
    Header forms, scopes, the keyless discovery endpoints, and rate-limit headers.
  </Card>

  <Card title="The time model" icon="clock" href="/concepts/time-model">
    Period, knowledge time, and `as_of`. The basis for lookahead-free backtests.
  </Card>

  <Card title="Macro screener" icon="filter" href="/guides/screener">
    Filter countries by canonical macro indicators with a compact DSL.
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdks/typescript">
    A typed, zero-dependency client with auto-pagination and screener helpers.
  </Card>
</CardGroup>

<Tip>
  Need help? Email [support@financialdatapi.com](mailto:support@financialdatapi.com) and include the `requestId` from the affected response. See [Support](/support).
</Tip>