Timeline

Overview

Get a chronological view of all documents for a company. View 10-Ks, 10-Qs, 8-Ks, and earnings calls organized by date, with optional grouping by quarter or year.

GET /v1/companies//timeline

Get the document timeline for a specific company.

Path Parameters

ticker

string

required

Stock ticker symbol (e.g., AAPL)

Query Parameters

doc_types

string

default:"all"

Comma-separated document types: 10-K, 10-Q, 8-K, EARNINGS_CALL, etc.

start_date

string

default:"1 year ago"

Filter events from this date forward (ISO 8601: YYYY-MM-DD)

end_date

string

default:"today"

Filter events up to this date (ISO 8601: YYYY-MM-DD)

include_8k_items

boolean

default:true

Include 8-K item codes in response

group_by

string

default:"none"

Group results:

none - Flat list (default)
quarter - Group by fiscal quarter
year - Group by fiscal year

limit

number

default:100

Maximum results (1-500)

Request Example

curl -X GET "https://api.fintool.com/v1/companies/AAPL/timeline" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (Ungrouped)

ticker

string

Stock ticker symbol

company_name

string

Full company name

timeline

array

Array of document events sorted by filing_date descending

Show Event Object

publication_id

string

SEC accession number or transcript ID

doc_type

string

Document type (10-K, 10-Q, 8-K, EARNINGS_CALL)

title

string

Document title

filing_date

string

Filing date (ISO 8601)

period

string

Reporting period (e.g., “FY 2024”, “Q3 2024”). Null for 8-Ks.

period_end_date

string

Period end date (ISO 8601). Null for 8-Ks.

items

array

8-K item codes (only for 8-K documents when include_8k_items=true)

Show Item Object

code

string

8-K item code (e.g., “2.02”)

title

string

Item title

is_material

boolean

Whether this is a material item

document_url

string

API URL to fetch document

transcript_url

string

API URL to fetch transcript (only for EARNINGS_CALL)

total

number

Total number of documents in timeline

date_range

object

Date range of the results

Show Date Range

start

string

Start date (ISO 8601)

end

string

End date (ISO 8601)

Response Example (Ungrouped)

{
  "ticker": "AAPL",
  "company_name": "Apple Inc.",
  "timeline": [
    {
      "publication_id": "0000320193-24-000123",
      "doc_type": "10-K",
      "title": "Annual Report for fiscal year ended September 28, 2024",
      "filing_date": "2024-11-01",
      "period": "FY 2024",
      "period_end_date": "2024-09-28",
      "items": null,
      "document_url": "/v1/documents/0000320193-24-000123"
    },
    {
      "publication_id": "tx_12345",
      "doc_type": "EARNINGS_CALL",
      "title": "Q4 2024 Earnings Call",
      "filing_date": "2024-11-01",
      "period": "Q4 2024",
      "period_end_date": "2024-09-28",
      "items": null,
      "document_url": "/v1/documents/tx_12345",
      "transcript_url": "/v1/transcripts/tx_12345"
    },
    {
      "publication_id": "0000320193-24-000089",
      "doc_type": "8-K",
      "title": "Current Report",
      "filing_date": "2024-11-01",
      "period": null,
      "period_end_date": null,
      "items": [
        {"code": "2.02", "title": "Results of Operations and Financial Condition", "is_material": true},
        {"code": "9.01", "title": "Financial Statements and Exhibits", "is_material": false}
      ],
      "document_url": "/v1/documents/0000320193-24-000089"
    },
    {
      "publication_id": "0000320193-24-000078",
      "doc_type": "10-Q",
      "title": "Quarterly Report for period ended June 29, 2024",
      "filing_date": "2024-08-02",
      "period": "Q3 2024",
      "period_end_date": "2024-06-29",
      "items": null,
      "document_url": "/v1/documents/0000320193-24-000078"
    }
  ],
  "total": 4,
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-11-15"
  }
}

Grouped Response

Use group_by=quarter or group_by=year to organize documents by period.

Request with Grouping

curl -X GET "https://api.fintool.com/v1/companies/AAPL/timeline?group_by=quarter&start_date=2023-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

Grouped Response Schema

ticker

string

Stock ticker symbol

company_name

string

Full company name

groups

array

Array of period groups

Show Group Object

period

string

Period label (e.g., “Q4 2024”, “FY 2024”)

fiscal_quarter

number

Fiscal quarter (1-4). Only for quarterly grouping.

fiscal_year

number

Fiscal year

start_date

string

Period start date (ISO 8601)

end_date

string

Period end date (ISO 8601)

events

array

Documents in this period (same Event Object schema as ungrouped)

document_count

number

Number of documents in this period

total

number

Total number of documents across all groups

Response Example (Grouped by Quarter)

{
  "ticker": "AAPL",
  "company_name": "Apple Inc.",
  "groups": [
    {
      "period": "Q4 2024",
      "fiscal_quarter": 4,
      "fiscal_year": 2024,
      "start_date": "2024-07-01",
      "end_date": "2024-09-30",
      "events": [
        {
          "publication_id": "0000320193-24-000123",
          "doc_type": "10-K",
          "title": "Annual Report",
          "filing_date": "2024-11-01",
          "document_url": "/v1/documents/0000320193-24-000123"
        },
        {
          "publication_id": "tx_12345",
          "doc_type": "EARNINGS_CALL",
          "title": "Q4 2024 Earnings Call",
          "filing_date": "2024-11-01",
          "transcript_url": "/v1/transcripts/tx_12345"
        }
      ],
      "document_count": 2
    },
    {
      "period": "Q3 2024",
      "fiscal_quarter": 3,
      "fiscal_year": 2024,
      "start_date": "2024-04-01",
      "end_date": "2024-06-30",
      "events": [
        {
          "publication_id": "0000320193-24-000078",
          "doc_type": "10-Q",
          "title": "Quarterly Report",
          "filing_date": "2024-08-02",
          "document_url": "/v1/documents/0000320193-24-000078"
        },
        {
          "publication_id": "tx_12344",
          "doc_type": "EARNINGS_CALL",
          "title": "Q3 2024 Earnings Call",
          "filing_date": "2024-08-01",
          "transcript_url": "/v1/transcripts/tx_12344"
        }
      ],
      "document_count": 2
    }
  ],
  "total": 4
}

Use Cases

Company Research

Get a complete view of a company’s filing history

Quarterly Review

Group documents by quarter to analyze trends

Event Monitoring

Track all 8-K material events for a company

Document Discovery

Find specific filings by type and date

import requests

ticker = "AAPL"
url = f"https://api.fintool.com/v1/companies/{ticker}/timeline"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

params = {
    "doc_types": "10-K,10-Q,EARNINGS_CALL",
    "start_date": "2022-01-01",
    "group_by": "quarter"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(f"Earnings History: {data['company_name']}\n")

for group in data["groups"]:
    print(f"{group['period']}:")
    for event in group["events"]:
        if event["doc_type"] == "EARNINGS_CALL":
            print(f"  Transcript: {event['transcript_url']}")
        else:
            print(f"  {event['doc_type']}: {event['document_url']}")

Example: Filter to 8-K Material Events

import requests

ticker = "AAPL"
url = f"https://api.fintool.com/v1/companies/{ticker}/timeline"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

params = {
    "doc_types": "8-K",
    "include_8k_items": True,
    "start_date": "2024-01-01"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(f"8-K Filings for {data['ticker']}\n")

for event in data["timeline"]:
    material_items = [i for i in event["items"] if i["is_material"]]
    if material_items:
        print(f"{event['filing_date']}")
        for item in material_items:
            print(f"  {item['code']}: {item['title']}")

Error Responses

Status	Code	Description
400	`invalid_doc_types`	Invalid document types parameter
400	`invalid_group_by`	Invalid group_by value
404	`company_not_found`	Ticker doesn’t exist

{
  "error": {
    "code": "company_not_found",
    "message": "Company with ticker 'INVALID' not found"
  }
}

Getting Started

API Reference

Guides

Overview

GET /v1/companies//timeline

Path Parameters

Query Parameters

Request Example

Response (Ungrouped)

Response Example (Ungrouped)

Grouped Response

Request with Grouping

Grouped Response Schema

Response Example (Grouped by Quarter)

Use Cases

Company Research

Quarterly Review

Event Monitoring

Document Discovery

Example: Filter to 8-K Material Events

Error Responses

Next Steps

Documents API

Transcripts API

Getting Started

API Reference

Guides

​Overview

​GET /v1/companies//timeline

​Path Parameters

​Query Parameters

​Request Example

​Response (Ungrouped)

​Response Example (Ungrouped)

​Grouped Response

​Request with Grouping

​Grouped Response Schema

​Response Example (Grouped by Quarter)

​Use Cases

Company Research

Quarterly Review

Event Monitoring

Document Discovery

​Example: Get Earnings-Related Documents

​Example: Filter to 8-K Material Events

​Error Responses

​Next Steps

Documents API

Transcripts API

Overview

GET /v1/companies//timeline

Path Parameters

Query Parameters

Request Example

Response (Ungrouped)

Response Example (Ungrouped)

Grouped Response

Request with Grouping

Grouped Response Schema

Response Example (Grouped by Quarter)

Use Cases

Example: Get Earnings-Related Documents

Example: Filter to 8-K Material Events

Error Responses

Next Steps