kibot

Adjustments Request

?action=adjustments returns the splits and dividends Kibot has on file for one symbol or for the whole catalog in a single call. Its main use is to answer one question cheaply: "Has anything happened to this symbol since the last date in my local file?" If not, fetch only the missing bars. If so, re-download the entire file, because Kibot's historical prices are back-adjusted retroactively. This article covers the parameters, the TAB-separated response shape, the bulk allsymbols mode, and the incremental-update pattern.

Request URL

https://api.kibot.com?action=adjustments
 &symbol=[symbol]
 &startdate=[startdate]
 &period=[period]
 &enddate=[enddate]
 &splitsonly=[splitsonly]
 &dividendsonly=[dividendsonly]
 &symbolsonly=[symbolsonly]

action and one date parameter, startdate or period, are required; every other parameter has a sensible default. A request without a date parameter is rejected with 400 Bad Request. Missing required date parameter.

Response shape

The body is TAB-separated values (not comma-separated as history returns), with a header row defining the field order:

Date Symbol Company Action Description EventDate
3/19/2016 SPY S&P 500 SPDRs 1.0496 Dividend 3/18/2016
12/20/2021 SPY SPDR S&P 500 ETF 1.6364 Dividend 12/17/2021
9/17/2022 SPY SPDR S&P 500 ETF 1.5964 Dividend 9/16/2022

The TAB separator is unusual: history uses commas, so it is a small parsing trap if the same code path handles both endpoints. The response has six TAB-separated columns:

  • Date: the date Kibot applied the adjustment to the published adjusted data (its processing date). It is typically 1 to 4 calendar days after the event date, can fall on a Saturday or Sunday, and for some historical events it equals the event date. It is not the ex-date.
  • Symbol: the ticker.
  • Company: the issuer or fund name on record for the event; informational, and it may differ across rows for the same symbol.
  • Action: the event value: the per-share dividend amount (four decimal places) or the split ratio (e.g. 10-1).
  • Description: the event type: Dividend, Split, or Reverse Split.
  • EventDate: the date of the corporate action itself; for dividends this is the ex-dividend date, the date prices drop by the dividend amount.

When &symbolsonly=1 is set, the response collapses to a plain newline-delimited list of tickers without any other fields.

Parameters

action (required)

Always adjustments for this endpoint.

symbol (optional)

Three modes:

  • A specific ticker, e.g. MSFT: returns adjustments for that symbol only.
  • allsymbols: returns adjustments for every symbol in the catalog in a single call. This is the throughput-efficient mode for batch update scripts.
  • Omitted entirely: equivalent to symbol=allsymbols; if no symbol is given, the server returns data for all available symbols.

Use symbol=allsymbols for any workflow updating more than a handful of symbols: one HTTP request returns all the adjustment data. One large response is dramatically cheaper than N per-symbol round trips.

startdate (required unless period is given)

Inclusive lower bound on the Date column (the processing date), formatted MM/DD/YYYY. Rules:

  • Either startdate or period must be present. A request with neither returns 400 Bad Request. Missing required date parameter. in the response body.
  • For the complete history of one symbol, pass an early date such as startdate=1/1/1960.
  • If both are given, startdate is used.

period (alternative to startdate)

A whole number of days counted back from today: period=30 is the same as a startdate 30 days ago, which suits a periodic update job that should not track a cursor date. It must be a positive integer; period=0 or a non-number returns 400 Bad Request. Invalid Period. period always counts back from today, even when enddate is given.

enddate (optional)

Inclusive upper bound on the Date column (the processing date), formatted MM/DD/YYYY. Defaults to the previous business day if omitted. Note that startdate and enddate filter on the Date column, not on EventDate: a query whose enddate is earlier than the processing date of an event will not return that event even if its ex-date falls inside the window. When reconstructing the full event list for a symbol, leave enddate at its default (the current value) and select the events you want by EventDate in your desired window.

splitsonly (optional)

1 returns only splits and reverse splits. 0 or omitted returns both splits and dividends.

dividendsonly (optional)

1 returns only dividends. 0 or omitted returns both splits and dividends. Setting both splitsonly=1 and dividendsonly=1 simultaneously is undefined; pick one.

symbolsonly (optional)

1 returns only the list of affected symbols, one per line, with no other fields and no TAB separators. Use it when you only need to know "which of my symbols changed?" and plan to refetch the full price file for each. 0 or omitted returns the full TAB-separated rows.

The incremental-update pattern

The endpoint's most important use case is the "did this symbol change since X?" check that Kibot Agent uses to decide what to download. The recipe is two API calls per symbol:

  1. Find the last date in your local file. For a CSV named IBM.txt whose final row dates to 5/1/2011, that string is the cursor.
  2. Ask the server: any adjustments since then? Call ?action=adjustments&symbol=IBM&startdate=5/1/2011.
  3. Branch on the response.
    • 405 Data Not Found: no splits or dividends since the cursor. The historical bars on disk are still correct; download only the new bars with a history call from 5/1/2011 forward.
    • Any rows returned: splits or dividends have happened since the cursor. Re-download the entire historical file, because every bar before 5/1/2011 has been back-adjusted on the server. There is no "patch" mode.

This branching is why the endpoint exists. Kibot's data is permanently back-adjusted: a stock that splits 2-for-1 today has every historical price divided by 2 retroactively, so a local file built last month is silently wrong from this month onward. The cheap pre-flight check turns a potentially expensive full refetch into a one-line conditional.

For accounts maintaining hundreds or thousands of symbols, scale the recipe by issuing a single ?action=adjustments&symbol=allsymbols&startdate=<earliest cursor> call, parsing the response into a "changed" set, and only refetching files for symbols in that set. This collapses N pre-flight calls into one and is the recommended bulk pattern.

Worked examples

Splits and dividends for one symbol since a specific date

https://api.kibot.com?action=adjustments&symbol=MSFT&startdate=2/16/2010

Returns every Microsoft split or dividend on or after February 16, 2010, formatted as TAB-separated rows.

Complete adjustment history for one symbol

https://api.kibot.com?action=adjustments&symbol=WMT&startdate=1/1/1960

With startdate set to an early date and a specific symbol given, returns every Walmart adjustment Kibot has on file, which is useful for first-time backfills or audit trails.

All symbols since a specific date

https://api.kibot.com?action=adjustments&symbol=allsymbols&startdate=5/1/2011

The bulk-update workhorse. Combined with symbolsonly=1, this collapses further to a "which of my symbols changed?" probe:

https://api.kibot.com?action=adjustments&symbol=allsymbols&startdate=5/1/2011&symbolsonly=1

Just the splits, no dividends

https://api.kibot.com?action=adjustments&symbol=allsymbols&splitsonly=1&startdate=1/1/2024

Use this if you track only structural events (those that make a price adjustment mandatory) and do not care about dividend cash flows.

Practical notes

The 405 Data Not Found response on a "no adjustments since cursor" query is not an error: it is a "nothing here" signal, so treat it as a normal branch in your code, not an exception. The same response is returned for a symbol that does not exist, so check the ticker separately if you need to tell the two apart. The full status code list is on the Server responses page.

Adjustment data is published with a small lag relative to the corresponding ex-date, so a script that runs an hour after market open on an ex-dividend day may briefly see no adjustment row even though the price has already been adjusted in the historical files. Re-running the check later in the day, or anchoring the script to the 8 AM ET ready time for daily updates (Data updates), avoids this race.

Background on what "adjusted" means at Kibot, the all-cash dividend treatment, the comparison with Yahoo Finance's split-only convention, and the formula used to back-adjust historical bars, lives in Adjusted vs unadjusted data.

Key Takeaways

  • ?action=adjustments returns TAB-separated splits and dividends; the separator differs from history, which uses commas.
  • A date parameter is required: pass startdate (MM/DD/YYYY) or period (days back from today). A request with neither is rejected with a 400 message.
  • The endpoint's primary purpose is the "did this symbol change since X?" pre-flight check that determines whether an incremental history fetch is safe or a full refetch is required.
  • 405 Data Not Found is the signal for "no adjustments since the cursor"; treat it as a normal branch, not an error.
  • For batch updates, use symbol=allsymbols once instead of per-symbol calls.
  • &symbolsonly=1 collapses the response to a plain ticker list when the caller only needs to know which symbols changed.