---
title: Filings
description: "Optional. Public companies' SEC filings. 2 tools."
group: filings
tools: [filings.latest, filings.read]
source: [packages/agents/src/tools/features.ts]
generated: true
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

Optional research tools: the SEC filings Roadstar stores for public companies. A business's own clients and suppliers are in [companies](/tools/companies/).

## How to use it

What `find_tools` sends with these tools, word for word:

> SEC filings stored for companies: 10-K, 10-Q, 8-K, 20-F, proxies and more.

## Tools

| Tool | What it does | Owner's yes |
| --- | --- | --- |
| [filings.latest](#latest) | Each company's latest filings | No |
| [filings.read](#read) | One filing's text | No |

## latest

`filings.latest` · Each company's latest filings.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `companyIds` | list of id | yes | 1–50 items |

Returns:

```ts
{
  items: Pick<CompanyListItem, "id" | "latestFiling">[];
}
```

## read

`filings.read` · One filing's text.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `accession` | text | yes | 1–40 characters |

Returns:

```ts
{
  state: string;
  title?: never;
  url?: never;
  text?: never;
} | {
  title: string | null;
  url: string | null;
  text: string;
  state?: never;
}
```

## Types

Named types in the results above.

```ts
type CompanyListItem = {
  id: string;
  manual?: boolean;
  handle: string;
  ticker: string | null;
  name: string;
  kind: string | null;
  kindLabel: string | null;
  quote: Quote | null;
  marketCap: number | null;
  watchlistMetrics: {
    sector: string | null;
    valuation: {
      label: string;
      value: string;
      period: string | null;
      sortValue?: number | null;
    } | null;
    revenueGrowth: {
      value: number;
      period: string;
    } | null;
    profitability: {
      label: string;
      value: number;
      period: string;
    } | null;
  };
  latestFiling: Pick<FilingItem, "what" | "filedAt"> | null;
  written: boolean;
  figures: {
    id: string;
    label: string;
    value: string;
    sortValue?: number | null;
    sortGroup?: string;
  }[];
  projects: {
    id: string;
    name: string;
  }[];
}

type Quote = {
  price: number;
  changePercent: number;
  asOf: string;
}

type FilingItem = {
  accession: string;
  form: string;
  what: string;
  period: string | null;
  filedAt: string;
}
```