Browse all documentation

Current account history API

Retrieve the quarterly current account balance in US dollars for one country, oldest first.

economics_get_current_account_history is available through REST and the economics_get_current_account_history MCP tool. Both return the same data shape and use the same credit.

Endpoint and request

REST endpoint
GET /v1/economics/{country}/current-account/observations
Example request
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/IDN/current-account/observations?start=2025-Q1&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP uses tool economics_get_current_account_history with the corresponding arguments below.

Parameters

The accepted period format for this operation is YYYY-QN.

NameRequiredTypeMeaning
countryYespath · ISO alpha-3One supported uppercase country code; see this operation’s coverage list.
startNoquery · YYYY-QNInclusive first observation period.
endNoquery · YYYY-QNInclusive last observation period.
limitNoquery · integer, 1–1000Maximum number of periods returned. Defaults to 100. A page may contain fewer periods; follow next_cursor.
cursorNoquery · opaque stringThe next_cursor from the previous page.
series_idNoquery · UUIDOptional. The `series_id` of one series, taken from an earlier answer. Omit it to read the country's default series.

Response

Example response
{
  "source": {
    "publisher": "Country authorities; National Summary Data Pages; European Central Bank; IMF Staff Estimates",
    "distributor": "International Monetary Fund"
  },
  "accounting_standard": "BPM6",
  "time_basis": "period_flow",
  "country": "IDN",
  "series_id": "b025aa04-14db-4649-87b8-359c20069196",
  "unit": "currency",
  "currency": "USD",
  "observations": [
    {
      "period": "2025-Q1",
      "value": "-68155035.6104999"
    },
    {
      "period": "2025-Q2",
      "value": "-2889388710.26253"
    }
  ],
  "next_cursor": "eyJhZnRlciI6IjIwMjUtUTIi…"
}

The history example asks for limit=2, so it holds two rows. next_cursor is shortened here. A real one is a longer opaque string.

FieldTypeRequiredMeaning
sourceobjectYesWho published the figure. publisher is the original publisher that the IMF's series metadata names, and distributor is the IMF, which Narwhal reads it from. One source per series, for its whole history. There is no released_on.
accounting_standardstringYesThe balance of payments manual the figure follows, for example BPM6.
time_basisstringYesAlways period_flow: the net flow over the quarter, not a stock.
countrystringYesThe requested uppercase ISO alpha-3 country code.
series_idstringYesThe series the figure comes from. Pass it as series_id to read the same series again.
unitstringYesAlways currency.
currencyISO 4217 stringYesAlways USD.
observationsarrayYesOldest-first observations, one per period. A page can hold fewer observations than limit. Follow next_cursor until it is null.
observations[].periodstringYesThe official month, quarter or year represented by the observation.
observations[].valuedecimal stringYesThe net current account balance for the quarter, in US dollars. A negative value is a deficit.
observations[].statusstringNoPresent only for a figure the publisher flags: estimated, break_in_series, definition_differs or break_in_series_and_definition_differs. Left out otherwise.
observations[].release_statusstringNopreliminary when the publisher marks the figure provisional. Left out otherwise.
next_cursorstring or nullYesPass this unchanged as cursor to read the next page. It is null on the last page.

Errors and credits

  • 400 invalid_query: A query parameter is unknown or repeated, country is not three uppercase letters, series_id is not a UUID, start or end is not a quarter in YYYY-QN format, start and end differ in format or start is after end, or limit is outside 1 to 1000. version_id, version and as_of are not accepted on this route.
  • 400 invalid_cursor: The cursor is malformed, or was issued for other filters.
  • 409 snapshot_unavailable: The cursor is more than 24 hours old and has expired. Start again without cursor.
  • 401 invalid_api_key: The Bearer key is missing or rejected.
  • 402 insufficient_credits: Your balance does not cover the call.
  • 404 series_not_found: The country is not in the coverage list on this page, series_id is not a series of that country, or the range holds no observation. A country outside the list gets a detail that says the family is not available for it. A 404 is not charged.
  • 429 rate_limit_exceeded: The network or account short-window limit was reached. Retry after Retry-After.
  • 503 economics_unavailable: Narwhal cannot safely serve the stored series.

Only a successful data response costs credit. See all errors, headers, and retry rules.

Freshness

This route returns Narwhal's current stored series, oldest first. Without start it begins at the oldest stored period, so pass start to read recent periods. It does not take as_of or version, so an earlier vintage cannot be read. Narwhal omits missing observations rather than filling them.

Read how source checks, validation, stored releases, and failed checks work.

Current public-beta coverage

9 Countries

ARG, CHN, IDN, KOR, MEX, SLV, THA, UKR, URY

Quarterly, in US dollars. The balance is the net of goods, services, income and transfers, and a negative value is a deficit. The International Monetary Fund (IMF) distributes the series, and source.publisher names the original publisher. A period is a quarter in YYYY-QN format. Any other country returns 404 not_found and is not charged.

Daily FX is available through the FX API.

Return to all Economics operations.

Was this page helpful?