kibot

Adjustments Request

?action=adjustments returns the splits and dividends Kibot has on file for a symbol, or for the whole catalogue in a single call. Its primary role in real workflows is not to enumerate corporate actions but to answer one question cheaply: "has anything happened to this symbol since the last date in my local file?". When the answer is no, the caller can fetch only the missing bars; when the answer is yes, the entire file must be re-downloaded because Kibot's historical prices have been back-adjusted retroactively. This article documents the parameters, the TAB-separated response shape, the bulk allsymbols mode, and the incremental-update pattern that makes the endpoint worth its existence.

Request URL

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

Only action is strictly required; every other parameter has a sensible default. Calling ?action=adjustments with no other arguments returns the last four months of all splits and dividends across the entire catalogue.

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
2/16/2010 MSFT Microsoft Corp. Dividend 0.1300
5/18/2010 MSFT Microsoft Corp. Dividend 0.1300
8/17/2010 MSFT Microsoft Corp. Dividend 0.1300

The TAB separator is unusual, history uses commas, and is a small parsing trap if the same code path handles both endpoints. The five columns are the date of the action, the ticker, the company name, the action type (Split, Reverse Split, Dividend), and a description that carries the dividend amount or split ratio.

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 catalogue 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.

The single-call allsymbols mode is the docs' explicit recommendation for any workflow updating more than a handful of symbols: "If you need to update multiple symbols, the fastest and most efficient way to obtain the required adjustment data is to use symbol=allsymbols parameter to return data using a single HTTP request" (per the adjustments docs). One large response is dramatically cheaper than N per-symbol round trips.

startdate (optional)

Inclusive lower bound, formatted MM/DD/YYYY. Behaviour depends on the symbol mode:

  • For a specific symbol: if startdate is omitted, the server returns the complete adjustment history for that symbol.
  • For allsymbols (or omitted symbol): if startdate is omitted, the server returns the last four months of adjustments, a practical default for periodic update jobs that run more frequently than quarterly.

enddate (optional)

Inclusive upper bound, formatted MM/DD/YYYY. Defaults to the previous business day if omitted.

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 and not documented; pick one.

symbolsonly (optional)

1 returns only the list of affected symbols, one per line, with no other fields and no TAB separators. Useful when the caller only needs to know "which of my symbols changed?" and intends 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 drives Kibot Agent and most third-party update scripts. The recipe (per the adjustments docs) 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. - 404 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. The entire historical file must be re-downloaded 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 documented bulk pattern.

Worked examples

Splits and dividends for one symbol since a specific date

http://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

http://api.kibot.com?action=adjustments&symbol=WMT

With startdate omitted and a specific symbol given, returns every Walmart adjustment Kibot has on file, useful for first-time backfills or audit trails.

All symbols since a specific date

http://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:

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

Just the splits, no dividends

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

Useful for callers tracking only structural events (price-affecting in a way that makes adjustment mandatory) and indifferent to dividend cash flows.

Practical notes

The 404 Not Found response on a "no adjustments since cursor" query is not an error, it is a successful "nothing here" signal that the calling code should treat as a normal branch, not an exception. The full status code list lives in Server responses.

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 Kibot Agent's published "ready by 8 AM ET" window for daily updates (Data updates), avoids this race.

Background on what "adjusted" actually 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.
  • The response defaults are deliberately asymmetric: a specific symbol returns full history, allsymbols (or no symbol) returns the last four months only.
  • 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.
  • 404 Not Found is the success 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, the docs explicitly recommend this for any non-trivial workflow.
  • &symbolsonly=1 collapses the response to a plain ticker list when the caller only needs to know which symbols changed.