> This page is for API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.spreadspace.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server.

# List feed

GET https://api.spreadspace.app/api/markets/feed

Lists the organization's feed, newest filing date first: each filing that landed, was extracted or was superseded for a company the organization follows, with the company's name and what the filing appended, and `unseen_count`, the events logged since the caller last marked the feed seen (0 for an API key). Pages by cursor: page on `has_more`, not on the page length. Needs a Market research subscription and `markets:read`.

Requires the `markets:read` scope. Rate limit: 200 requests per minute per key (the `api` lane).

Reference: https://docs.spreadspace.app/api/api-reference/markets-feed/list

## Authentication

- `Authorization` header (bearer token, required) — Bearer token. Use `ss_live_…` for live data or `ss_test_…` for the sandbox (test mode). See [Authentication](https://docs.spreadspace.app/api/authentication).

## Request

### Query parameters

- `cursor` (string, optional) — The `next_cursor` from the previous page; omit for the first page.
- `limit` (integer, optional) — Page size, 1 to 100; 50 when absent.

### Headers

- `SpreadSpace-Version` (string, optional) — Pin the API version, e.g. `2026-10-07`. Omit to get the latest. See [Versioning](https://docs.spreadspace.app/api/versioning).

## Response

### 200

OK

- `data` (list of MarketsFeedItemView, required) — The page of events, newest filing date first.
- `has_more` (boolean, required) — True when another page follows this one, false on the last page.
- `unseen_count` (integer, required) — The feed's events that are not historical and were logged after the member last marked the feed seen; 0 for an API key.
- `next_cursor` (string, optional, nullable) — An opaque string to pass as `cursor` for the next page; null when there are no more events.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope.

### 401 Unauthorized Error

Unauthorized: the bearer token or API key is missing or invalid.

- `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope.

### 403 Forbidden Error

Forbidden: authentication succeeded but the caller is not permitted to perform this action, for example an API key missing the required scope, an embed session reaching a loan it was not minted for, or a feature outside the workspace's plan.

- `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope.

### 404 Not Found Error

Not found: the resource does not exist or is not visible to the calling tenant.

- `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope.

### 429 Too Many Requests Error

Too many requests: the rate limit was hit, or an idempotency-key replay is still in progress.

- `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope.

### 500 Internal Server Error

Internal server error: an unexpected failure. Quote the `request_id` in support tickets. A mutation sent with an `Idempotency-Key` replays this fault under that key rather than re-running; confirm the resource state before resending with a new key.

- `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope.

## Types

### MarketsFeedItemView

One event in the organization's Markets feed: a filing of a followed company that landed, was extracted, or was superseded by an amendment.

- `id` (string, required) — The event's id.
- `accession` (string, required) — The filing's SEC accession number.
- `cik` (string, required) — The company's SEC Central Index Key, ten digits with its leading zeros.
- `form` (string, required) — The form type as filed, such as 10-K, 10-Q, 8-K or S-1.
- `kind` (string, required) — What happened to the filing: landed, extracted or superseded.
- `filing_date` (date, required) — The date the filing was made; for a superseded event, the amendment's.
- `appended_at` (datetime, required) — When the event was logged.
- `historical` (boolean, required) — The filing was dated more than 30 days before the event: listed at its filing date, never counted as unseen, never sent as a webhook.
- `appends` (MarketsFeedAppends, required) — What the filing appended.
- `registrant_name` (string, optional, nullable) — The registrant's name; null when the store holds no registrant row for it.

### ApiErrorBody

Inner body of the canonical API error envelope.

- `type` (enum, required) — Stable error type identifier, one of the values listed. Pattern-match on this value, not the human-readable message. A later version may add a value; treat one you do not know by its HTTP status.
  - Allowed values: `billing_required`, `business_email_required`, `conflict`, `counterparty_not_in_plan`, `cursor_expired`, `custom_visual_limit_exceeded`, `doc_too_large`, `embed_not_in_plan`, `embed_origin_not_allowed`, `embed_scope_exceeds_key`, `embed_scope_not_allowed`, `embed_session_binding_mismatch`, `embed_session_not_found`, `embed_token_expired`, `forbidden`, `geometry_plan_denied`, `html_upload_disabled`, `idempotency_in_progress`, `idempotency_request_mismatch`, `idempotency_response_too_large`, `insufficient_credits`, `insufficient_scope`, `internal_error`, `invalid_code`, `invalid_cursor`, `invalid_embed_token`, `invalid_include`, `invalid_limit`, `invalid_request`, `invalid_session_handle`, `invalid_version`, `key_expired`, `key_revoked`, `last_item`, `license_assigned`, `license_holder_has_license`, `license_none_free`, `license_reassign_window`, `licenses_assigned`, `markets_api_required`, `memo_locked`, `memo_not_locked`, `mfa_enrollment_required`, `mode_mismatch`, `not_found`, `payload_too_large`, `payment_failed`, `pii_claim_required`, `rate_limited`, `render_failed`, `request_cancelled`, `research_not_in_plan`, `resource_gone`, `same_origin_required`, `sandbox_missing`, `sandbox_organization`, `scope_not_in_product`, `scope_state_changed`, `session_handle_already_used`, `session_handle_expired`, `session_handle_revoked`, `spend_cap_reached`, `spread_already_finalized`, `spread_limit`, `spread_locked`, `spread_not_finalized`, `spread_not_locked`, `spread_not_ready`, `spread_template_limit_exceeded`, `spreads_not_in_plan`, `spreadsheet_upload_disabled`, `statement_mapping_not_in_plan`, `subscription_required`, `surface_limit_exceeded`, `test_key_remint_required`, `unauthorized`, `unknown_factor`, `unprocessable`, `usage_throttled`, `validation_failed`
- `message` (string, required) — Human-readable error message. Subject to wording changes; do not parse.
- `code` (string, optional) — A finer, stable identifier within `type`, on the errors that carry one; absent otherwise. Pattern-match on it like `type`. The upload presign answers `not_found` with `loan_not_found` and `invalid_request` with `borrower_loan_mismatch`.
- `request_id` (string, optional, nullable) — Per-request correlation ID (matches `X-Request-ID` response header). Quote in support tickets.
- `details` (map from string to string, optional, nullable) — Structured detail. Some error types populate documented keys in every environment: a version conflict (409) carries `current_version`, the version the resource is actually at, so the client can reload and re-apply. Free-form diagnostic detail beyond those keys appears in development environments only. An `insufficient_credits` 402 carries `balance_usd`, `reserved_usd`, `in_flight_docs`, `incoming_docs` and `per_doc_reservation_usd` as decimal strings.

### MarketsFeedAppends

What a filing appended to the organization's Markets feed.

- `form` (string, required) — The form type as filed.
- `statements` (list of MarketsFeedStatement, required) — The statements the filing added, each with its period end; empty when none.
- `tables` (list of string, required) — The titles of the supporting tables the filing added; empty when none.
- `periods` (list of date, required) — The distinct dated period ends across the filing's documents, ascending; empty when none.
- `extractor_version` (string, optional, nullable) — The extractor version the filing's documents were extracted under; null when the event is no extraction or the version is unknown.
- `superseded_by` (string, optional, nullable) — The accession number of the amendment that took the filing's place; null unless the event is a supersede.

### MarketsFeedStatement

One statement a filing appended to the organization's Markets feed.

- `document_type` (string, required, nullable) — The statement's document type, such as income_statement or balance_sheet; null when the extraction named none.
- `period_end` (date, required, nullable) — The statement's period end; null when the extraction named none or printed no date.

## Examples

**Response**

```json
{
  "data": [
    {
      "id": "0195a2c4e6f8a0b1c2d3e4f5",
      "accession": "0009900077-26-000012",
      "cik": "0009900077",
      "form": "10-K",
      "kind": "extracted",
      "filing_date": "2026-03-02",
      "appended_at": "2026-03-02T06:15:12.418210+00:00",
      "historical": false,
      "appends": {
        "form": "10-K",
        "statements": [
          {
            "document_type": "balance_sheet",
            "period_end": "2025-12-31"
          },
          {
            "document_type": "income_statement",
            "period_end": "2025-12-31"
          },
          {
            "document_type": "cash_flow_statement",
            "period_end": "2025-12-31"
          }
        ],
        "tables": [
          "Property, plant and equipment",
          "Long-term debt"
        ],
        "periods": [
          "2025-12-31"
        ],
        "extractor_version": "v2026.02.21a-v2026.02.18b",
        "superseded_by": null
      },
      "registrant_name": "Larkspur Mills Inc"
    },
    {
      "id": "0195a2c4d1e0a0b1c2d3e4f4",
      "accession": "0009900077-26-000012",
      "cik": "0009900077",
      "form": "10-K",
      "kind": "landed",
      "filing_date": "2026-03-02",
      "appended_at": "2026-03-02T05:58:40.003117+00:00",
      "historical": false,
      "appends": {
        "form": "10-K",
        "statements": [],
        "tables": [],
        "periods": [],
        "extractor_version": null,
        "superseded_by": null
      },
      "registrant_name": "Larkspur Mills Inc"
    }
  ],
  "has_more": false,
  "unseen_count": 2,
  "next_cursor": null
}
```

**SDK Code**

```typescript
import { SpreadSpace } from '@spreadspace/sdk';

const client = new SpreadSpace({ apiKey: process.env.SPREADSPACE_API_KEY! });

for await (const item of client.markets.feed.list({ limit: 20 })) {
  console.log(item.form, item.registrant_name, item.filing_date);
}

```

```python
import os

from spreadspace import SpreadSpace

client = SpreadSpace(api_key=os.environ["SPREADSPACE_API_KEY"])

for item in client.markets.feed.list(limit=20):
    print(item["form"], item["accession"])

```

```csharp
using SpreadSpace;

using var client = new SpreadSpaceClient(Environment.GetEnvironmentVariable("SPREADSPACE_API_KEY"));

await foreach (var item in client.Markets.Feed.List(limit: 20))
    Console.WriteLine($"{item.Accession} {item.RegistrantName}");

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spreadspace.app/api/markets/feed?limit=20"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.spreadspace.app/api/markets/feed?limit=20")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.spreadspace.app/api/markets/feed?limit=20")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.spreadspace.app/api/markets/feed?limit=20', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.spreadspace.app/api/markets/feed?limit=20")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```