---
title: "List workspace company financial history"
description: "Requires a workspace-bound API key with intel:finint. Returns only that workspace's recorded observations, newest recorded first. Not available with anonymous x402 payment. Metric filtering uses an index. FactType is applied to each bounded page, so an empty page can still have a next cursor. History reflects retained Y2 observations, not complete filing coverage or guaranteed historical availability. SEC imports retain JSON record pointers, not page/quote spans, and do not establish original publication timestamps. Unsupported or repeated query parameters are rejected with HTTP 400."
canonical: https://y2.dev/docs/api/reference/intel/listCompanyFinancialObservationsV2/
---

Endpoint Reference[Intel](https://y2.dev/docs/api/reference/intel)

# List workspace company financial history

Requires a workspace-bound API key with intel:finint. Returns only that workspace's recorded observations, newest recorded first. Not available with anonymous x402 payment. Metric filtering uses an index. FactType is applied to each bounded page, so an empty page can still have a next cursor. History reflects retained Y2 observations, not complete filing coverage or guaranteed historical availability. SEC imports retain JSON record pointers, not page/quote spans, and do not establish original publication timestamps. Unsupported or repeated query parameters are rejected with HTTP 400.

`GET https://api.y2.dev/api/v2/entities/{entityId}/financial-observations`

- Operation ID: `listCompanyFinancialObservationsV2`
- Required scopes: `intel:finint`
- Contract: https://y2.dev/openapi.json

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entityId` | path | string | Yes | Stable public entity ID from the entity API. |
| `metricKey` | query | string | No | Exact normalized metric key, such as eps_diluted. |
| `factType` | query | `actual`, `estimate`, `guidance` | No |  |
| `limit` | query | integer | No |  |
| `cursor` | query | string | No | Opaque next cursor. Preserve the path and filters between pages. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Bounded workspace financial observations. | `CompanyFinancialHistoryResponse` |
| 400 | Invalid request parameters |  |
| 401 | Missing or invalid API key |  |
| 403 | Insufficient permissions or access denied |  |
| 404 | Resource not found |  |
| 429 | Rate limit exceeded (per-key or per-account aggregate) |  |
| 500 | Internal server error |  |

### 200 response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[]` | array of object |  |
| `data[].metric` | object |  |
| `data[].factType` | `actual`, `estimate`, `guidance` |  |
| `data[].filing` | `CompanyFilingFact` |  |
| `data[].value` | object |  |
| `data[].period` | object |  |
| `data[].confidence` | number |  |
| `data[].comparison` | object |  |
| `data[].sources[]` | array of string (uri) |  |
| `data[].availableAt` | string (date-time) | Conservative evidence-availability bound, using the latest retained source capture across all cited sources. Only present when every cited source has a verified archived span. Not the original publication date or a historical retrieval guarantee. |
| `data[].availabilityBasis` | `first_capture`, `unknown` | first_capture requires revision-validated spans for all cited sources. Legacy, incomplete, or source-only evidence remains unknown. |
| `data[].provenance[]` | array of `CompanyFinancialSourceProvenance` |  |
| `data[].recordedAt` | string (date-time) | Time the financial observation was recorded by Y2, independently of its reporting period and source times. |
| `data[].id` | string |  |
| `data[].type` | string |  |
| `meta` | `PublicListMeta` |  |
| `meta.count` | integer |  |
| `meta.pageCount` | integer |  |
| `meta.limit` | integer |  |
| `meta.isDone` | boolean |  |
| `meta.hasMore` | boolean |  |
| `meta.nextCursor` | string or null |  |
| `meta.asOf` | string (date-time) |  |
| `meta.page` | `PublicPageMeta` |  |
| `links` | `PublicCollectionLinks` |  |
| `links.self` | string |  |
| `links.next` | string or null |  |