# Sources

Find research sources by name, domain, or source ID

> Section: API reference

> Last updated: **2026-10-17**.

> API version: **v1 (Latest)**. OpenAPI publication: **2026-11-08**.

## `GET /v1/sources`

Find research sources by name, domain, or company. Browse your workspace's source index, including source identity, ticker coverage, and access rights. An indexed source is not necessarily authorized for content access.

Lifecycle: **stable**. Availability: **released**. Authentication: **Bearer API key**.

## Examples

Requires a Bearer API key. Replace `<api-key>` in each request with your developer key. Uses an included request or $0.02 in enabled prepaid credit for a successful new billable read.

Response excerpts below illustrate the shape only; placeholders and empty arrays are not live research or proof of coverage. Actual responses include additional fields.

### Find research sources for a company

Browse source records associated with a ticker. Use q to search by name or topic, domain to filter the research domain, or source_id to select one record.

```bash
curl --request GET \
  --url 'https://beliefstate.ai/v1/sources?ticker=NVDA&limit=25' \
  --header 'Authorization: Bearer <api-key>'
```

Response excerpt:

```json
{
  "data": [],
  "page": {
    "nextCursor": null
  }
}
```

Indexed sources are not automatically authorized for content access. An unmatched source_id returns an empty array. Follow page.nextCursor when present.

## Request

```bash
curl --request GET \
  --url 'https://beliefstate.ai/v1/sources?limit=25' \
  --header 'Authorization: Bearer <api-key>'
```

```javascript
const options = { method: "GET", headers: {"Authorization":"Bearer <api-key>"} };

fetch("https://beliefstate.ai/v1/sources?limit=25", options)
  .then((response) => response.json())
  .then((data) => console.log(data));
```

```python
import requests

url = "https://beliefstate.ai/v1/sources?limit=25"
headers = {"Authorization":"Bearer <api-key>"}

response = requests.get(url, headers=headers)
print(response.text)
```

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Request-ID` | header | `string` | no | Stable ID for an idempotent retry. Reuse it only for the same logical request. |
| `view` | query | `enum` | no | Use news for free retained SEC filings; omit for the source directory. |
| `include_earnings` | query | `boolean` | no | For view=news, include admitted SEC-sourced earnings schedules when available. |
| `q` | query | `string` | no | Search sources by name or topic. |
| `source_id` | query | `string<uuid>` | no | Filter to one source ID. An unknown ID returns an empty result. |
| `ticker` | query | `string` | no | Filter by an observed security ticker. |
| `domain` | query | `enum` | no | Filter by a supported research domain. |
| `strategy` | query | `enum` | no | Filter by a supported investment strategy. |
| `accessType` | query | `enum` | no | Filter by accessType. |
| `acquisitionTier` | query | `enum` | no | Filter by acquisitionTier. |
| `researchDensity` | query | `enum` | no | Filter by researchDensity. |
| `professional` | query | `boolean` | no | Filter by professional. |
| `corpusEligible` | query | `boolean` | no | Filter by corpusEligible. |
| `freeOnly` | query | `boolean` | no | Filter by freeOnly. |
| `limit` | query | `integer` | no | Maximum sources to return, from 1 to 100. Default: 25. |
| `cursor` | query | `string<uuid>` | no | UUID cursor returned by the previous page. |

## Response includes

- Canonical source and identity metadata
- Observed security coverage and research classifications
- Access, rights, acquisition, and corpus eligibility state
- Pagination metadata

## Response schemas

### 200 Successful read only response (response variant 1 of 2)

- `schema_version` ("1", required)
- `generated_at` (string, required)
- `data` (object[], required)
- `page` (object, required)
  - `limit` (integer, required)
  - `nextCursor` (string<uuid>, required)
  - `total` (integer, required)

### 200 Successful read only response (response variant 2 of 2)

- `resource` ("issuer_news", required)
- `access` ("free", required)
- `ticker` (string, required)
- `source` ("SEC EDGAR", required)
- `scope` (retained_recent_filings | current_recent_filings, required)
- `status` (available | stale | unavailable, required)
- `observed_at` (string<date-time>, required)
- `checked_at` (string<date-time>, required)
- `data` (object[], required)
  - `accession_number` (string, required)
  - `form` (string, required)
  - `filed_on` (string<date>, required)
  - `accepted_at` (string<date-time>, required)
  - `url` (string<uri>, required)
- `earnings_schedule` (object)
  - `status` (available | unavailable, required)
  - `data` (object[], required)
    - `fiscal_year` (integer, required)
    - `fiscal_quarter` (integer, required)
    - `release_date` (string<date>, required)
    - `release_session` (string, required)
    - `webcast_at` (string<date-time>, required)
    - `filed_on` (string<date>, required)
    - `accepted_at` (string<date-time>, required)
    - `observed_at` (string<date-time>, required)
    - `available_at` (string<date-time>, required)
    - `url` (string<uri>, required)

### 400 Invalid input

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 401 Authentication failed

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 402 Paid access required

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 404 Security unavailable

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 409 Duplicate request ID

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 503 Stored intelligence temporarily unavailable

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

## Agent feedback

Report unclear, stale, or incorrect documentation through [BeliefState support](https://beliefstate.ai/contact). Include this page URL and the smallest reproducible detail.

<!-- BeliefState-Origin: https://beliefstate.ai/docs/api/sources; Content-Fingerprint: bs-sha256-4b5bd68f55f2aade4dd406fef5675104607ab190a3bac01b4d7631b1e471c48e -->