> ## Documentation Index > Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > The Financial Datasets API is served at https://api.financialdatasets.ai. Authenticate with the `X-API-KEY` header; create keys at https://financialdatasets.ai. Agents can open and fund their own account without a dashboard: see https://docs.financialdatasets.ai/agents.md. > Tool-using agents can call Financial Datasets without writing code through the hosted MCP server at https://mcp.financialdatasets.ai/. > The OpenAPI spec at https://financialdatasets.ai/openapi.json is the source of truth for request and response schemas. > The index of every docs page is at https://docs.financialdatasets.ai/llms.txt. Append .md to any docs URL to get that page as Markdown. # GDP Data API > US GDP and income history in 12 series: real GDP growth from 1947, real and nominal GDP, the four contributions to growth, income-side growth, corporate profits, personal income, the saving rate, and real consumer spending, with the change from the prior period and from a year earlier. ### Overview The Financial Datasets GDP API returns one US growth or income series per request: real GDP growth, the real and nominal level of GDP, the four contributions to growth, income-side growth (GDI), corporate profits, personal income, the saving rate, and real consumer spending, with the change from the prior period and from a year earlier computed for you. It covers 12 series from 1947 to today, updated within minutes of each release. The quarterly series start in 1947, personal income and the saving rate in 1959, and real consumer spending in 2007. The data comes directly from authoritative government sources ([data provenance](https://docs.financialdatasets.ai/data-provenance.md)). You can call it as a REST endpoint with an API key, or from Claude, ChatGPT, Cursor, and other AI apps through the [MCP server](https://docs.financialdatasets.ai/mcp-server.md), or pay per request with [x402](https://docs.financialdatasets.ai/x402.md). [Pricing](https://www.financialdatasets.ai/pricing) starts at \$20. Values are in each series' own units (percent, percentage points, billions of dollars); the changes are in the same units, plus a percent change over the year for dollar series. To get started, please create an account and grab your **API key** at [financialdatasets.ai](https://financialdatasets.ai). You will use the API key to authenticate your API requests. ### Coverage | History | Series | Updated | | - | - | - | | 1947 to today | 12 | Quarterly and monthly | ### Series Every series is seasonally adjusted. Quarterly (`date` is the first day of the quarter): | Series | What it is | Units | From | | - | - | - | - | | `real_gdp_growth` | Real GDP, percent change from the preceding quarter, annual rate | Percent | 1947 | | `real_gdp` | Real GDP, annual rate | Billions of chained 2017 dollars | 1947 | | `nominal_gdp` | GDP in current dollars, annual rate | Billions of dollars | 1947 | | `consumer_spending_contribution` | Contribution of consumer spending to real GDP growth | Percentage points | 1947 | | `investment_contribution` | Contribution of private investment to real GDP growth | Percentage points | 1947 | | `net_exports_contribution` | Contribution of net exports to real GDP growth | Percentage points | 1947 | | `government_contribution` | Contribution of government spending and investment to real GDP growth | Percentage points | 1947 | | `real_gdi_growth` | Real gross domestic income, percent change from the preceding quarter, annual rate | Percent | 1947 | | `corporate_profits` | Corporate profits with inventory valuation and capital consumption adjustments, annual rate | Billions of dollars | 1947 | Monthly (`date` is the first day of the month): | Series | What it is | Units | From | | - | - | - | - | | `personal_income` | Personal income, annual rate | Billions of dollars | 1959 | | `saving_rate` | Personal saving as a percentage of disposable personal income | Percent | 1959 | | `real_consumer_spending` | Real personal consumption expenditures, annual rate | Billions of chained 2017 dollars | 2007 | You can fetch this list, with each series' frequency and first available date, with a free `GET` request to: [https://api.financialdatasets.ai/macro/gdp/series/](https://api.financialdatasets.ai/macro/gdp/series/) ### Reading the fields * `date` is the reference period, not the release date: the first day of the quarter for quarterly series (`2026-07-01` is the third quarter of 2026, first published in late October) and the first day of the month for monthly series. * `value` is the published figure in the series' units. Dollar series are in billions at a seasonally adjusted annual rate. The growth rates are quarter over quarter at an annual rate. * The four contributions are in percentage points and add up to `real_gdp_growth`, within rounding. * `change_prior` is `value` minus the prior period's value: the prior quarter for quarterly series, the prior month for monthly. Same units as `value`. * `change_year` is `value` minus the value one year earlier: the same quarter or month a year back. Same units as `value`. * `change_year_pct` is `change_year` as a percent of the year-earlier value, rounded to one decimal. For `real_gdp` it is the year-over-year growth rate. It is `null` for series measured in percent or percentage points: their change is stated in points, in `change_year`. * A change is `null` when the comparison period was not published. * Each quarter is estimated three times, about a month apart (advance, second, third). History holds the latest published values: each estimate replaces the one before it. * `real_gdi_growth` and `corporate_profits` are published with a later estimate of a quarter than the other quarterly series, so their newest row can be one quarter behind. ### Getting Started There are only 3 steps for making a successful API call: 1. Add your API key to the header of the request as `X-API-KEY`. 2. Add the `series` parameter, which is required. Optionally add `start_date` and `end_date` (inclusive, `YYYY-MM-DD`). Any day inside a quarter or month selects that period. With no dates you get the trailing five years. 3. Execute the API request. Rows come newest first in pages of up to 10. When more rows remain, the response includes a `next_page_url`; request it as-is to get the next page. See the [pagination guide](https://docs.financialdatasets.ai/guides/pagination.md). ### Example ```python GDP theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import requests # add your API key to the headers headers = { "X-API-KEY": "your_api_key_here" } # set parameters series = 'real_gdp_growth' # required start_date = '2025-07-01' # optional end_date = '2026-09-30' # optional # create the URL with parameters url = ( f'https://api.financialdatasets.ai/macro/gdp' f'?series={series}' f'&start_date={start_date}' f'&end_date={end_date}' ) # make API request response = requests.get(url, headers=headers) # parse the observations from the response gdp = response.json().get('gdp') ``` ### Example Response ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "gdp": [ { "series": "real_gdp_growth", "date": "2026-07-01", "value": 3.4, "change_prior": 1.2, "change_year": -0.5, "change_year_pct": null }, { "series": "real_gdp_growth", "date": "2026-04-01", "value": 2.2, "change_prior": -0.3, "change_year": -1.8, "change_year_pct": null } ] } ``` ### FAQ #### Is `date` the release date? No. `date` is the reference period. For quarterly series it is the first day of the quarter: `2026-07-01` is the third quarter of 2026, first published in late October. For monthly series it is the first day of the month. #### Are the three estimates of a quarter included? History holds the latest published values. Each quarter is estimated three times, about a month apart, and each estimate replaces the stored values. To receive each estimate as it is published, subscribe to the `gdp.created` [webhook](https://docs.financialdatasets.ai/webhooks/events.md). #### How do I get year-over-year GDP growth? Request `real_gdp` and read `change_year_pct`. `real_gdp_growth` is the quarter-over-quarter rate at an annual rate, the headline number of each release. #### Why is `change_year_pct` null for some series? It is `null` for series measured in percent or percentage points. A rate's change is stated in points, in `change_year`. #### Can an AI agent use this data? Yes. Claude, ChatGPT, Cursor, and other MCP clients reach it through the [Financial Datasets MCP server](https://docs.financialdatasets.ai/mcp-server.md). An agent with a wallet can also pay per request with [x402](https://docs.financialdatasets.ai/x402.md), with no account. ## OpenAPI ````yaml GET /macro/gdp openapi: 3.0.1 info: title: Financial Datasets API description: >- Stock market API with real-time and historical financial data for 27,000+ tickers over 30+ years. Financial statements, equity prices, insider trades, SEC filings, and more. version: 1.0.0 license: name: MIT url: https://opensource.org/licenses/MIT contact: name: API Support url: mailto:support@financialdatasets.ai email: support@financialdatasets.ai termsOfService: https://financialdatasets.ai/terms-of-use servers: - url: https://api.financialdatasets.ai/ description: Production server security: - X-API-KEY: [] tags: - name: Financial Statements description: Access to income statements, balance sheets, and cash flow statements - name: Market Data description: Real-time and historical price data - name: Company Information description: Company facts like ticker, name, and description - name: Earnings description: Earnings data and related information - name: News description: Real-time and historical news articles - name: SEC Filings description: SEC filings and regulatory documents - name: Insider Trades description: Insider trading activity and transactions - name: Activist Ownership description: Activist stakes from SEC Schedule 13D filings, in real time - name: Beneficial Ownership description: >- Holders of more than 5% of a company's shares, from SEC Schedules 13D and 13G - name: Insider Ownership description: Insider ownership statements from SEC Forms 3 and 5 - name: Institutional Holdings description: SEC-direct 13F equity holdings of institutional investment managers - name: IPOs description: >- Upcoming IPOs from SEC registration statements (Form S-1), with extracted pre-IPO financial statements - name: Index Funds description: >- ETF and index-fund holdings, weights, and the funds that hold a given security - name: Financial Metrics description: Financial ratios, metrics, and key performance indicators - name: Macroeconomics description: Real-time and historical macroeconomic data like interest rates - name: KPIs description: Sector-specific operational KPIs extracted from earnings releases. - name: Agent Account description: Self-serve account creation and funding for AI agents. - name: Search description: Search financial documents with one question and get cited passages back paths: /macro/gdp: get: tags: - Macroeconomics summary: GDP (Historical) description: >- US growth and income history for one series (real GDP growth, real and nominal GDP, the four contributions to growth, income-side growth, corporate profits, personal income, the saving rate, real consumer spending), newest first, with the change from the prior period and from a year earlier. Dates are reference periods: the first day of the quarter for quarterly series, the first day of the month for monthly series. Values are in the series' units (dollar series in billions at an annual rate), sourced from authoritative government sources, and hold the latest published estimate. A change is null when the comparison period was not published; change_year_pct is null for series measured in percent or percentage points. operationId: getGDP parameters: - name: series in: query description: >- The series id, e.g. real_gdp_growth. Nine quarterly series (real_gdp_growth, real_gdp, nominal_gdp, consumer_spending_contribution, investment_contribution, net_exports_contribution, government_contribution, real_gdi_growth, corporate_profits) and three monthly ones (personal_income, saving_rate, real_consumer_spending), all seasonally adjusted. Use the /macro/gdp/series endpoint to get the list. required: true schema: type: string - name: start_date in: query description: >- The first period to return, inclusive, in YYYY-MM-DD format; any day inside a quarter or month selects that period. Defaults to five years before end_date when both dates are omitted; omit it with an end_date to get all available history through that date. required: false schema: type: string - name: end_date in: query description: >- The last period to return, inclusive, in YYYY-MM-DD format. Defaults to today. required: false schema: type: string - name: cursor in: query description: >- Opaque pagination cursor from a previous response's next_page_url. When provided, all other query parameters are ignored: the cursor carries the original request's filters. Treat it as opaque; do not construct or modify it. required: false schema: type: string responses: '200': description: GDP response content: application/json: schema: $ref: '#/components/schemas/GDPResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' components: schemas: GDPResponse: type: object properties: gdp: type: array items: $ref: '#/components/schemas/GDPObservation' next_page_url: type: string description: >- Absolute URL of the next page of results. Present only when more results remain; request it as-is to continue. Each page holds up to 10 records. GDPObservation: type: object properties: series: type: string description: The series id, e.g. real_gdp_growth. date: type: string description: >- The reference period in YYYY-MM-DD format: the first day of the quarter for quarterly series (2026-07-01 for the third quarter of 2026), the first day of the month for monthly series. Not the release date. value: type: number nullable: true description: >- The published figure in the series' units (percent, percentage points, billions of dollars at an annual rate), as of the latest estimate. Null when the period was not published. change_prior: type: number nullable: true description: >- value minus the prior period's value (prior quarter or prior month), in the same units. Null when either period was not published. change_year: type: number nullable: true description: >- value minus the value one year earlier (the same quarter or month a year back), in the same units. Null when either period was not published. change_year_pct: type: number nullable: true description: >- change_year as a percent of the year-earlier value, rounded to one decimal. Null when either period was not published, and always null for series measured in percent or percentage points, whose change is stated in points in change_year. ErrorResponse: type: object properties: error: type: string description: A short error message. message: type: string description: A more detailed error message. responses: BadRequestError: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Bad Request message: Invalid request parameters UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized message: Invalid API key provided PaymentRequiredError: description: The request requires a paid subscription content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Payment Required message: >- This endpoint requires a paid subscription. Please upgrade your plan. NotFoundError: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Not Found message: Ticker XXXX not found securitySchemes: X-API-KEY: type: apiKey name: X-API-KEY description: API key for authentication. in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.