> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sacra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with datasets & revenue data

> Use company_datasets from the Sacra API to build revenue charts, valuation timelines, and fundraising histories

Every company profile returned by `/api/v1/companies/` includes a `company_datasets` array — chart-ready time series data you can plot directly. Each dataset is a named series of `{x, y}` points covering revenue, valuation, fundraising, and share price history.

This guide walks through a real response (Kraken) to show how the data is structured and how to turn it into charts.

## When to use `company_datasets`

| Use case                                  | Best option                                                                |
| ----------------------------------------- | -------------------------------------------------------------------------- |
| Drop-in chart with no custom UI           | [Embed endpoints](/guides/display-company-data#embeds)                     |
| Chart-ready time series for custom charts | `company_datasets` on `/api/v1/companies/`                                 |
| Granular metrics with citations           | [`/api/v1/metrics/`](/guides/display-company-data#fetch-financial-metrics) |
| Funding round details                     | [`/api/v1/events/`](/guides/display-company-data#fetch-funding-events)     |

`company_datasets` is the sweet spot when you want to build your own charts without having to aggregate raw metric rows yourself. The data comes pre-aggregated and sorted chronologically.

***

## Fetch company datasets

Request Kraken's company profile:

```bash theme={null}
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sacra.com/api/v1/companies/?company_domain=kraken.com"
```

The `company_datasets` array lives inside the `company` object alongside `financials`, `documents`, and other fields:

```json theme={null}
{
  "company": {
    "id": 239,
    "name": "Kraken",
    "domain": "kraken.com",
    "financials": [ ... ],
    "company_datasets": [
      {
        "id": "0fcc2ca9-ba40-4301-95e6-807341de19dc",
        "name": "Kraken: Revenue ($M)",
        "data_type": "Revenue",
        "metric": "USD",
        "frequency": "Year",
        "x_label": "Time",
        "y_label": "Revenue",
        "data": [
          { "x": "2022-12-31T00:00:00.000Z", "y": 1010000000, "type": "historical" },
          { "x": "2023-12-31T00:00:00.000Z", "y": 696300000, "type": "historical" },
          { "x": "2024-12-31T00:00:00.000Z", "y": 1658800000, "type": "historical" },
          { "x": "2025-12-31T00:00:00.000Z", "y": 2204000000, "type": "historical" }
        ],
        "source_type": "Google Sheets",
        "start_date": "2022-12-31T00:00:00Z",
        "end_date": "2025-12-31T00:00:00Z"
      },
      ...
    ]
  }
}
```

A single company can have multiple datasets spanning different data types.

***

## Dataset object reference

Each object in `company_datasets` has these fields:

| Field         | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| `id`          | string | Unique dataset identifier (UUID)                                      |
| `name`        | string | Human-readable label, e.g. `"Kraken: Revenue ($M)"`                   |
| `data_type`   | string | What the dataset measures (see [dataset types](#dataset-types) below) |
| `metric`      | string | Unit — `"USD"` or `"Percent"`                                         |
| `frequency`   | string | Granularity — `"Year"` or `"Month"`                                   |
| `x_label`     | string | Suggested x-axis label                                                |
| `y_label`     | string | Suggested y-axis label                                                |
| `data`        | array  | Array of data points (see below)                                      |
| `source_type` | string | Data provenance — `"Google Sheets"`, `"Filing"`, `"AI Search"`        |
| `source_url`  | string | Link to the underlying source                                         |
| `start_date`  | string | Earliest data point date                                              |
| `end_date`    | string | Latest data point date                                                |
| `status`      | string | `"Active"` for live datasets                                          |
| `created_at`  | string | When the dataset was first created                                    |
| `updated_at`  | string | When the dataset was last modified                                    |
| `company`     | number | Company ID                                                            |

### Data points

Each entry in the `data` array has this shape:

```json theme={null}
{
  "x": "2024-12-31T00:00:00.000Z",
  "y": 1658800000,
  "type": "historical",
  "meta": { ... }
}
```

| Field  | Type           | Description                                       |
| ------ | -------------- | ------------------------------------------------- |
| `x`    | string         | ISO 8601 timestamp — the date for this data point |
| `y`    | number         | The value — raw numeric, no pre-formatting        |
| `type` | string         | `"historical"` for observed data                  |
| `meta` | object \| null | Optional metadata that varies by dataset type     |

<Note>
  `y` values are always raw numbers. Revenue of $1.66B is returned as `1658800000`, not `1658.8` or `"$1.66B"\`. Format values for display in your UI.
</Note>

<Tip>
  Date conventions for revenue data points follow the same rules described in the [Revenue concepts page](/concepts/revenue#datapoint-periods): December 31 dates are full-year figures, any other month-end date is year-to-date.
</Tip>

***

## Dataset types

Here are the dataset types you'll find in `company_datasets`, illustrated with Kraken's data:

### Revenue

Annual or year-to-date revenue figures in USD.

```json theme={null}
{
  "data_type": "Revenue",
  "metric": "USD",
  "data": [
    { "x": "2022-12-31T00:00:00.000Z", "y": 1010000000, "type": "historical" },
    { "x": "2023-12-31T00:00:00.000Z", "y": 696300000, "type": "historical" },
    { "x": "2024-12-31T00:00:00.000Z", "y": 1658800000, "type": "historical" },
    { "x": "2025-12-31T00:00:00.000Z", "y": 2204000000, "type": "historical" }
  ]
}
```

### Revenue Growth Rate

Year-over-year revenue growth as a decimal. A value of `1.38` means 138% growth, `-0.28` means a 28% decline.

```json theme={null}
{
  "data_type": "Revenue Growth Rate",
  "metric": "Percent",
  "data": [
    { "x": "2023-12-31T00:00:00.000Z", "y": -0.2796, "type": "historical" },
    { "x": "2024-12-31T00:00:00.000Z", "y": 1.3823, "type": "historical" },
    { "x": "2025-12-31T00:00:00.000Z", "y": 0.3287, "type": "historical" }
  ]
}
```

<Note>
  Growth rates are decimals, not percentages. Multiply by 100 for display: `(y * 100).toFixed(1) + "%"`.
</Note>

### Valuation

Company valuation at each funding event. The `meta` object identifies the specific round.

```json theme={null}
{
  "data_type": "Valuation",
  "metric": "USD",
  "data": [
    {
      "x": "2019-06-25T00:00:00.000Z",
      "y": 4000000000,
      "type": "historical",
      "meta": {
        "name": "Growth 2019",
        "status": "closed",
        "event_id": "fr_ded4bbd8-86e5-4748-afa7-5cde4961a91a",
        "event_type": "funding_round",
        "event_subtype": "growth"
      }
    },
    {
      "x": "2025-07-29T00:00:00.000Z",
      "y": 15000000000,
      "type": "historical",
      "meta": {
        "name": "Series C 2025",
        "status": "closed",
        "event_id": "fr_982c6a4f-6d6b-4a1e-97c8-53351cf67ccb",
        "event_type": "funding_round",
        "event_subtype": "series_c"
      }
    }
  ]
}
```

### Amount Raised

Total capital raised per year, aggregated across all rounds in that year. The `meta` object includes the aggregation method and number of events.

```json theme={null}
{
  "data_type": "Amount Raised",
  "metric": "USD",
  "data": [
    {
      "x": "2014-12-31T00:00:00.000Z",
      "y": 5000000,
      "type": "historical",
      "meta": { "year": 2014, "aggregation": "annual_sum", "event_count": 1 }
    },
    {
      "x": "2025-12-31T00:00:00.000Z",
      "y": 1000000000,
      "type": "historical",
      "meta": { "year": 2025, "aggregation": "annual_sum", "event_count": 2 }
    }
  ]
}
```

### Price per Share

Share price at each funding round. The `meta` object links back to the specific event.

```json theme={null}
{
  "data_type": "Price per Share",
  "metric": "USD",
  "data": [
    {
      "x": "2013-01-31T00:00:00.000Z",
      "y": 0.03,
      "type": "historical",
      "meta": { "name": "Seed 2013", "event_subtype": "seed" }
    },
    {
      "x": "2025-09-25T00:00:00.000Z",
      "y": 61.47,
      "type": "historical",
      "meta": { "name": "Growth (2025)", "event_subtype": "growth" }
    }
  ]
}
```

### Issue Price

Similar to Price per Share but sourced from filings. May contain the same values with different provenance.

```json theme={null}
{
  "data_type": "Issue Price",
  "metric": "USD",
  "data": [
    { "x": "2013-01-31T00:00:00.000Z", "y": 0.03, "type": "historical" },
    { "x": "2025-11-21T00:00:00.000Z", "y": 61.47, "type": "historical" }
  ]
}
```

***

## Filtering datasets by type

To find a specific dataset, filter the array by `data_type`:

```js theme={null}
const datasets = company.company_datasets;

const revenue = datasets.find(d => d.data_type === "Revenue");
const growth = datasets.find(d => d.data_type === "Revenue Growth Rate");
const valuation = datasets.find(d => d.data_type === "Valuation");
const raised = datasets.find(d => d.data_type === "Amount Raised");
const sharePrice = datasets.find(d => d.data_type === "Price per Share");
```

<Note>
  Not every company will have every dataset type. Always check that the dataset exists before accessing its data.
</Note>

***

## Example: revenue chart

This React component fetches a company and renders a revenue bar chart using [Recharts](https://recharts.org/).

```jsx theme={null}
import { useState, useEffect } from "react";
import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer } from "recharts";

function RevenueChart({ domain }) {
  const [chartData, setChartData] = useState(null);

  useEffect(() => {
    fetch(`/api/sacra/company?domain=${domain}`)
      .then((res) => res.json())
      .then(({ company }) => {
        const dataset = company.company_datasets.find(
          (d) => d.data_type === "Revenue"
        );
        if (!dataset) return;

        setChartData(
          dataset.data.map((point) => ({
            year: new Date(point.x).getFullYear(),
            revenue: point.y,
          }))
        );
      });
  }, [domain]);

  if (!chartData) return <div>Loading...</div>;

  const formatUSD = (value) =>
    `$${(value / 1e9).toFixed(1)}B`;

  return (
    <ResponsiveContainer width="100%" height={400}>
      <BarChart data={chartData}>
        <XAxis dataKey="year" />
        <YAxis tickFormatter={formatUSD} />
        <Tooltip formatter={(value) => formatUSD(value)} />
        <Bar dataKey="revenue" fill="#E8B84B" />
      </BarChart>
    </ResponsiveContainer>
  );
}
```

This renders a bar chart showing Kraken's annual revenue from 2022 through 2025, with values formatted as billions.

***

## Example: valuation timeline

Valuation datasets include `meta` with the funding round name, which you can use as data point labels.

```jsx theme={null}
import { useState, useEffect } from "react";
import {
  LineChart, Line, XAxis, YAxis, Tooltip, ResponsiveContainer,
  LabelList,
} from "recharts";

function ValuationTimeline({ domain }) {
  const [chartData, setChartData] = useState(null);

  useEffect(() => {
    fetch(`/api/sacra/company?domain=${domain}`)
      .then((res) => res.json())
      .then(({ company }) => {
        const dataset = company.company_datasets.find(
          (d) => d.data_type === "Valuation"
        );
        if (!dataset) return;

        setChartData(
          dataset.data.map((point) => ({
            date: new Date(point.x).toLocaleDateString("en-US", {
              year: "numeric",
              month: "short",
            }),
            valuation: point.y,
            label: point.meta?.name || "",
          }))
        );
      });
  }, [domain]);

  if (!chartData) return <div>Loading...</div>;

  const formatUSD = (value) =>
    `$${(value / 1e9).toFixed(0)}B`;

  return (
    <ResponsiveContainer width="100%" height={400}>
      <LineChart data={chartData}>
        <XAxis dataKey="date" />
        <YAxis tickFormatter={formatUSD} />
        <Tooltip formatter={(value) => formatUSD(value)} />
        <Line type="monotone" dataKey="valuation" stroke="#E8B84B" strokeWidth={2}>
          <LabelList dataKey="label" position="top" />
        </Line>
      </LineChart>
    </ResponsiveContainer>
  );
}
```

For Kraken, this plots two points: Growth 2019 ($4B) and Series C 2025 ($15B), each labeled with the round name from `meta`.

***

## Example: fundraising history table

For fundraising data, a table is often more useful than a chart since the Amount Raised dataset is aggregated annually while Price per Share is per-round.

```jsx theme={null}
function FundraisingHistory({ company }) {
  const raised = company.company_datasets.find(
    (d) => d.data_type === "Amount Raised"
  );
  const sharePrice = company.company_datasets.find(
    (d) => d.data_type === "Price per Share"
  );

  const formatUSD = (value) => {
    if (value >= 1e9) return `$${(value / 1e9).toFixed(1)}B`;
    if (value >= 1e6) return `$${(value / 1e6).toFixed(1)}M`;
    return `$${value.toFixed(2)}`;
  };

  return (
    <div>
      {raised && (
        <table>
          <thead>
            <tr>
              <th>Year</th>
              <th>Amount Raised</th>
              <th>Rounds</th>
            </tr>
          </thead>
          <tbody>
            {raised.data.map((point) => (
              <tr key={point.x}>
                <td>{point.meta?.year ?? new Date(point.x).getFullYear()}</td>
                <td>{formatUSD(point.y)}</td>
                <td>{point.meta?.event_count ?? "—"}</td>
              </tr>
            ))}
          </tbody>
        </table>
      )}

      {sharePrice && (
        <table>
          <thead>
            <tr>
              <th>Date</th>
              <th>Round</th>
              <th>Price per Share</th>
            </tr>
          </thead>
          <tbody>
            {sharePrice.data.map((point) => (
              <tr key={point.x}>
                <td>
                  {new Date(point.x).toLocaleDateString("en-US", {
                    year: "numeric",
                    month: "short",
                  })}
                </td>
                <td>{point.meta?.name || "—"}</td>
                <td>{formatUSD(point.y)}</td>
              </tr>
            ))}
          </tbody>
        </table>
      )}
    </div>
  );
}
```

For Kraken, the share price table shows the progression from $0.03 at Seed (2013) to $61.47 at the Growth round (2025) — a \~2,000x increase.

***

## Tips

* **Values are raw numbers.** Revenue of \$2.2B is returned as `2204000000`. Always format for display.
* **Growth rates are decimals.** A `y` of `1.38` on a Revenue Growth Rate dataset means 138% growth. Multiply by 100 for percentage display.
* **Not every company has every dataset type.** Always check that `find()` returns a result before accessing `.data`.
* **Date conventions matter.** December 31 dates are full-year figures; other month-end dates are year-to-date. See the [Revenue concepts page](/concepts/revenue#datapoint-periods) for details.
* **`meta` varies by dataset type.** Valuation and Price per Share datasets include funding round details (`name`, `event_subtype`, `event_id`). Amount Raised includes aggregation info (`year`, `event_count`). Revenue datasets typically have no `meta`.
* **Use `/events/` for richer funding data.** If you need investor names, round details, or secondary transactions beyond what `meta` provides, query the [`/api/v1/events/`](/guides/display-company-data#fetch-funding-events) endpoint.
* **Use `/metrics/` for citations.** Datasets don't include citation sources. If you need to show where a revenue figure came from, use [`/api/v1/metrics/`](/guides/display-company-data#fetch-financial-metrics) which returns full citation chains.