Get Streams (Bulk)

Overview

POST /v2/streams/bulk returns confirmed streams using the same Stream objects as Get Streams. This is a public endpoint. No API key is required. It uses POST only so that multi-valued filters can be sent in the request body. Despite the verb, it is a read-only query: nothing is created or modified, and the result set is not scoped to any API key’s organization. This endpoint is the bulk counterpart of Get Streams. Reach for it when Get Streams is too limited, specifically when you need to:

Filter by multiple values at once: several stream IDs, several organizations, one or more target-token chains, or a set of (chainId, address) target tokens, instead of the single-value query params accepted by Get Streams.
Paginate the result set with the optional page and limit query params.

Filters of different kinds are combined with AND; multiple values within a single filter are combined with OR. As with Get Streams, only confirmed streams are ever returned.

targetChainIds and targetTokens filter on each stream’s target token (the token tracked via customArgs.targetTokenId), not its reward token. Use the decimal EVM chain IDs listed in Get Tokens.

Endpoint

Filter by multiple stream IDs

curl -X POST "https://earn.turtle.xyz/v2/streams/bulk" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "6f0f2a1c-1c2d-4f3e-9a8b-7c6d5e4f3a2b"
    ]
  }'

const response = await fetch('https://earn.turtle.xyz/v2/streams/bulk', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ids: [
      '550e8400-e29b-41d4-a716-446655440000',
      '6f0f2a1c-1c2d-4f3e-9a8b-7c6d5e4f3a2b',
    ],
  }),
});

const data = await response.json();

Filter by chain and token (no org ID)

This is the no-auth-context path for a frontend that only needs to read reward streams for specific tokens on specific chains. It passes no distributor or organization ID and needs no API key. Send targetChainIds, targetTokens, or both.

curl -X POST "https://earn.turtle.xyz/v2/streams/bulk?limit=50" \
  -H "Content-Type: application/json" \
  -d '{
    "targetChainIds": [1, 8453],
    "targetTokens": [
      { "chainId": 1, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
    ]
  }'

const response = await fetch(
  'https://earn.turtle.xyz/v2/streams/bulk?limit=50',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      targetChainIds: [1, 8453],
      targetTokens: [
        { chainId: 1, address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' },
      ],
    }),
  }
);

const data = await response.json();

Filter by organizations and target tokens

curl -X POST "https://earn.turtle.xyz/v2/streams/bulk" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationIds": ["9f51b66a-d13a-4b55-8515-ae6e4ef7cf25"],
    "targetChainIds": [1, 8453],
    "targetTokens": [
      { "chainId": 1, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
    ],
    "withSnapshots": false,
    "usersCount": true
  }'

const response = await fetch('https://earn.turtle.xyz/v2/streams/bulk', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    organizationIds: ['9f51b66a-d13a-4b55-8515-ae6e4ef7cf25'],
    targetChainIds: [1, 8453],
    targetTokens: [
      { chainId: 1, address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' },
    ],
    withSnapshots: false,
    usersCount: true,
  }),
});

const data = await response.json();

Paginate the result set

Pagination is opt-in. Send page and/or limit as query parameters to receive one page plus a pagination object in the response.

curl -X POST "https://earn.turtle.xyz/v2/streams/bulk?page=1&limit=50" \
  -H "Content-Type: application/json" \
  -d '{ "organizationIds": ["9f51b66a-d13a-4b55-8515-ae6e4ef7cf25"] }'

const response = await fetch(
  'https://earn.turtle.xyz/v2/streams/bulk?page=1&limit=50',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      organizationIds: ['9f51b66a-d13a-4b55-8515-ae6e4ef7cf25'],
    }),
  }
);

const data = await response.json();

Parameters

Request Body

All body fields are optional. Sending an empty body is allowed, but only together with a bounded limit query parameter (see Response Semantics).

uuid[]

Filter by stream IDs. Returns streams whose id is in this list.

uuid[]

Filter by owning organization IDs. Returns streams belonging to any of these organizations.

integer[]

Filter by streams whose target token is on any of these chains. Values are decimal EVM chain IDs. See Get Tokens for the supported list.

EvmToken[]

Filter by streams whose target token matches any of these EVM (chainId, address) tokens.

boolean

default:"false"

Include the full historical snapshots array for each returned stream. Behaves exactly as on Get Streams.

boolean

default:"false"

Add userCount and activeUserCount to each included snapshot object. Behaves exactly as on Get Streams.

`EvmToken`

integer

required

Decimal EVM chain ID of the target token.

string

required

Target token contract address on that chain. Matching is case-insensitive.

Query Parameters

Pagination is optional. Omit both parameters to return all matching streams in a single response, without a pagination object.

integer

Page number for the paginated result set. Providing page or limit switches the endpoint into paginated mode. Values lower than 1 are normalized by the backend to 1.

integer

Number of streams to return per page. Providing page or limit switches the endpoint into paginated mode. Values lower than 1 are normalized to 20. Values above 500 are rejected with 400 Invalid Argument.

Response Example

When pagination is requested, the response includes a pagination object. The streams array holds the same Stream objects documented in Get Streams.

{
  "streams": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "chainId": 1,
      "contractAddress": "0x4C6F5a1aA2B9985d4A8b9189C2118E7f55E2f701",
      "orgId": "9f51b66a-d13a-4b55-8515-ae6e4ef7cf25",
      "type": 2,
      "strategy": "Fixed APR",
      "startTimestamp": "2026-03-11T00:00:00Z",
      "endTimestamp": "2026-04-11T00:00:00Z",
      "lastSnapshot": { "...": "see Get Streams for the full Stream object" },
      "snapshots": [],
      "rewardToken": { "...": "see Get Streams" },
      "estimatedLiveApr": "0.12"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 128,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false
  }
}

The Stream object is identical to the one returned by Get Streams. See that page for the complete field-by-field schema, including customArgs, adapters, point, lastSnapshot, committedSnapshot, snapshots, rewardToken, and estimatedLiveApr. As on Get Streams, use estimatedLiveApr — not lastSnapshot.apr — for the rate a stream is currently distributing; see Live APR vs snapshot APR.

Response Semantics

Filters combine with AND, values within a filter with OR

Sending organizationIds and targetChainIds together returns streams that belong to one of the organizations and whose target token is on one of the chains. Within a single filter, multiple values are matched with OR (an IN lookup).

Pagination is opt-in

If you omit both page and limit, the endpoint returns every matching stream and no pagination object. As soon as either query parameter is present, the response is paginated and includes a pagination object.

A bounded limit is required when no filter is provided

To avoid loading the entire stream table, an empty body (no ids, organizationIds, targetChainIds, or targetTokens) must be paired with a bounded limit query parameter. Without a filter and without a limit, the request is rejected with 400 Invalid Argument.

Only confirmed streams are returned

Like Get Streams, this endpoint only returns streams whose creation has been confirmed. Pending streams are never included.

An empty result is valid

If no stream matches the provided filters, the endpoint returns streams: [] (together with a pagination object when pagination was requested) rather than failing.

Response Fields

streams: Stream[]
pagination?: PaginationResponse

Stream[]

required

List of confirmed streams matching the provided filters. Each item is a Stream object, including estimatedLiveApr. See Get Streams for the full schema.

PaginationResponse

Pagination metadata describing the current page and the total size of the result set. Present only when page or limit was supplied; omitted otherwise.

`PaginationResponse`

integer

Current page returned by the backend after normalization.

integer

Number of items returned per page after normalization or capping.

integer

Total number of streams matching the filters across all pages.

integer

Total number of available pages for the current limit.

boolean

Whether a page after the current one exists.

boolean

Whether a page before the current one exists.

Error Handling

Missing filter without a bounded limit

Status Code: 400 Bad Request

{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "a bounded limit (max 500) is required when no filter is provided"
  }
}

Solution: Provide at least one filter (ids, organizationIds, targetChainIds, or targetTokens), or supply a bounded limit query parameter.

Too many filter values

Status Code: 400 Bad RequestEach filter has an upper bound: 100 ids, 20 organizationIds, 5 targetChainIds, and 100 targetTokens. Exceeding any of these returns INVALID_ARGUMENT with a message such as too many stream ids (max 100).Solution: Split large requests into multiple calls that stay within the per-filter limits.

Limit too high

Status Code: 400 Bad Request

{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "limit too high (max 500)"
  }
}

Solution: Request a limit of 500 or fewer and page through the result set.

Unexpected internal error

Status Code: 500 Internal Server ErrorSolution: Retry the request and contact Turtle if the issue persists.

Get Started

Products

Reference

Overview

Endpoint

Filter by multiple stream IDs

Filter by chain and token (no org ID)

Filter by organizations and target tokens

Paginate the result set

Parameters

Request Body

`EvmToken`

Query Parameters

Response Example

Response Semantics

Response Fields

`PaginationResponse`

Error Handling

​Overview

​Endpoint

​Filter by multiple stream IDs

​Filter by chain and token (no org ID)

​Filter by organizations and target tokens

​Paginate the result set

​Parameters

​Request Body

​EvmToken

​Query Parameters

​Response Example

​Response Semantics

​Response Fields

​PaginationResponse

​Error Handling

Overview

Endpoint

Filter by multiple stream IDs

Filter by chain and token (no org ID)

Filter by organizations and target tokens

Paginate the result set

Parameters

Request Body

`EvmToken`

Query Parameters

Response Example

Response Semantics

Response Fields

`PaginationResponse`

Error Handling