Skip to main content
GET
/
v1
/
filings
/
trends
Filing trends (time series)
curl --request GET \
  --url https://api.ivory.finance/v1/filings/trends \
  --header 'X-API-Key: <api-key>'
{
  "granularity": "<string>",
  "total_filings": 123,
  "series": [
    {
      "period": "2023-12-25",
      "count": 123,
      "by_form_type": {}
    }
  ],
  "company_id": "<string>",
  "cik": "<string>",
  "company_name": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

Returns a time-series of filing counts, optionally scoped to a single company, form type, or calendar year. Useful for charting a company’s disclosure cadence or monitoring market-wide activity over time.

​
Granularity

The granularity parameter controls the size of each bucket in the series array:
ValueBucket sizeExample period
weekISO calendar week2024-01-01
monthCalendar month2024-03-01
quarterCalendar quarter2024-07-01
yearCalendar year2024-01-01
All period values are the start date of their bucket (ISO 8601 date).

​
Scoping to a single year

Use the year parameter to restrict the series to one calendar year. This is more convenient than combining from_date / to_date and works with any granularity. 
GET /v1/filings/trends?year=2020
GET /v1/filings/trends?year=2020&granularity=month
GET /v1/filings/trends?year=2020&granularity=week&form_type=8-K
GET /v1/filings/trends?company_id=TSLA:NASDAQ&granularity=quarter
GET /v1/filings/trends?company_id=SHEL:LON&granularity=month
GET /v1/filings/trends?year=2020&company_id=0001318605&granularity=quarter
GET /v1/filings/trends?year=2020&company_id=GB:00445790&granularity=quarter
When year is supplied it takes precedence over from_date. Valid range: 1993–current year. The company_id parameter accepts any company identifier:
FormatExample
TICKER:EXCHANGETSLA:NASDAQ, SHEL:LON
CC:external_idGB:00445790, US:0001318605
UUID3f2a1b4c-...
Bare CIK0001318605

​
Example response

{
  "company_id": "0001318605",
  "cik": "0001318605",
  "company_name": "Tesla, Inc.",
  "granularity": "month",
  "total_filings": 47,
  "series": [
    {
      "period": "2020-01-01",
      "count": 4,
      "by_form_type": { "8-K": 3, "4": 1 }
    },
    {
      "period": "2020-02-01",
      "count": 6,
      "by_form_type": { "8-K": 2, "4": 3, "SC 13G": 1 }
    }
  ]
}

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
company_id
string | null

Filter to a specific company (UUID, CC:external_id, or CIK)

​
granularity
string
default:month

Bucket size: week | month | quarter | year

​
form_type
string | null

Filter by form type, e.g. 10-K, 8-K

​
from_date
string<date> | null

Start date (YYYY-MM-DD). Omit for full history.

​
year
integer | null

Scope results to a single calendar year, e.g. 2020. Takes precedence over from_date when both are supplied.

Response

Successful Response

​
granularity
string
required
​
total_filings
integer
required
​
series
TrendBucket · object[]
required
​
company_id
string | null
​
cik
string | null
​
company_name
string | null