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

# Get Streams

> Retrieve confirmed streams, optionally filtered by stream ID or organization ID

## Overview

`GET /v2/streams/` returns confirmed streams. This is a public endpoint — no API key is required.

* If no query parameters are sent, the endpoint returns all confirmed streams.
* Use `id` to retrieve a specific stream by its UUID.
* Use `orgId` to filter results to streams belonging to a specific organization.

This endpoint is intended for backoffice dashboards, reporting tools, campaign managers, and partner integrations that need to inspect stream configurations.

## Endpoint

### Get all streams

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://earn.turtle.xyz/v2/streams/?withSnapshots=false&usersCount=false"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    'https://earn.turtle.xyz/v2/streams/?withSnapshots=false&usersCount=false'
  );

  const data = await response.json();
  ```
</CodeGroup>

### Get streams filtered by organization

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://earn.turtle.xyz/v2/streams/?orgId=9f51b66a-d13a-4b55-8515-ae6e4ef7cf25"
  ```

  ```typescript TypeScript theme={null}
  const orgId = '9f51b66a-d13a-4b55-8515-ae6e4ef7cf25';

  const response = await fetch(
    `https://earn.turtle.xyz/v2/streams/?orgId=${orgId}`
  );

  const data = await response.json();
  ```
</CodeGroup>

### Get one stream by ID

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://earn.turtle.xyz/v2/streams/?id=550e8400-e29b-41d4-a716-446655440000&withSnapshots=true&usersCount=true"
  ```

  ```typescript TypeScript theme={null}
  const streamId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://earn.turtle.xyz/v2/streams/?id=${streamId}&withSnapshots=true&usersCount=true`
  );

  const data = await response.json();
  ```
</CodeGroup>

**Query Parameters**

<ParamField query="id" type="uuid">
  Optional stream identifier. When provided, the endpoint filters the result set to that stream ID.
</ParamField>

<ParamField query="orgId" type="uuid">
  Optional organization identifier. When provided, the endpoint returns only streams belonging to that organization.
</ParamField>

<ParamField query="withSnapshots" type="boolean" default="false">
  Include the full historical `snapshots` array for each returned stream.
</ParamField>

<ParamField query="usersCount" type="boolean" default="false">
  Add `userCount` and `activeUserCount` to each included snapshot object.
</ParamField>

## Response Example

```json theme={null}
{
  "streams": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "chainId": 1,
      "contractAddress": "0x4C6F5a1aA2B9985d4A8b9189C2118E7f55E2f701",
      "userId": null,
      "orgId": "9f51b66a-d13a-4b55-8515-ae6e4ef7cf25",
      "admin": "0x1111111111111111111111111111111111111111",
      "type": 2,
      "createdAt": "2026-03-10T12:00:00Z",
      "updatedAt": "2026-03-10T12:15:00Z",
      "startTimestamp": "2026-03-11T00:00:00Z",
      "endTimestamp": "2026-04-11T00:00:00Z",
      "totalAmount": "2500000000000000000000",
      "creationConfirmedAt": "2026-03-10T12:04:32Z",
      "snapshotComputationPaused": false,
      "merkleTreeComputationPaused": true,
      "hashCommitmentPaused": true,
      "claimPaused": true,
      "customArgs": {
        "targetTokenId": "8cc2ed9d-bd59-42fd-9df5-329fa22497b6",
        "apr": "0.12",
        "targetToken": {
          "id": "8cc2ed9d-bd59-42fd-9df5-329fa22497b6",
          "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": 6,
          "isNative": false,
          "logoUrl": "https://...",
          "chain": {
            "id": "f4c8c3d9-6ae5-4dfa-8d33-7d7bb0a9e73c",
            "name": "Ethereum",
            "slug": "ethereum",
            "chainId": "1",
            "isTestnet": false,
            "logoUrl": "https://...",
            "ecosystem": "evm",
            "status": "active",
            "explorerUrl": "https://etherscan.io"
          },
          "active": true,
          "priceUsd": 1,
          "canonicalAssetId": "f4a35f17-7482-4d93-bc75-2ebd4f483d22",
          "streamsMinAmount": "1000000",
          "totalTurtleTvl": 10234567.12
        }
      },
      "adapters": [],
      "point": null,
      "strategy": "Fixed APR",
      "lastSnapshot": {
        "timestamp": "2026-03-11T00:00:00Z",
        "amountDistributed": "8123456789012345678",
        "amountBase": "8123456789012345678",
        "rootHash": null,
        "commitTxHash": null,
        "createdAt": "2026-03-11T00:01:00Z",
        "updatedAt": "2026-03-11T00:01:00Z",
        "tvl": "152340.12",
        "baseTvl": "152340.12",
        "baseApr": "0.105",
        "apr": "0.12",
        "rewardTokenPrice": "1.00",
        "customMetrics": {},
        "customArgs": {},
        "userCount": 124,
        "activeUserCount": 118
      },
      "committedSnapshot": null,
      "snapshots": [],
      "rewardToken": {
        "id": "56b0fab0-5c3e-49f6-a0a7-57e38d5ea999",
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "chainId": 1,
        "logoUrl": "https://...",
        "isAllowedRewardToken": true
      }
    }
  ]
}
```

## Response Semantics

<AccordionGroup>
  <Accordion title="No parameters means list all streams">
    If you omit all query parameters, the endpoint returns all confirmed streams across all organizations.
  </Accordion>

  <Accordion title="id is a filter, not a path selector">
    If you send `id`, the endpoint still returns a `streams` array. The array will contain either one matching stream or be empty if no stream with that ID exists.
  </Accordion>

  <Accordion title="orgId narrows results to one organization">
    If you send `orgId`, only streams belonging to that organization are returned. You can combine `orgId` with `id` to look up a specific stream within a specific organization.
  </Accordion>
</AccordionGroup>

## Stream Fields

The response body contains a `streams` array. Each item in that array is a `Stream` object with the fields described below.

```typescript theme={null}
streams: Stream[]
```

<ResponseField name="streams" type="Stream[]" required>
  List of confirmed streams matching the provided filters.
</ResponseField>

### `Stream`

<ResponseField name="id" type="uuid">
  Unique stream identifier.
</ResponseField>

<ResponseField name="chainId" type="integer | null">
  Decimal EVM chain ID for on-chain streams. `null` for point-based streams that do not deploy a contract.
</ResponseField>

<ResponseField name="contractAddress" type="string | null">
  Deployed on-chain stream contract address when available. It can be `null` for point-based streams or token-based streams that are still pending confirmation.
</ResponseField>

<ResponseField name="userId" type="uuid | null">
  Optional user identifier associated with the stream when present.
</ResponseField>

<ResponseField name="orgId" type="uuid">
  Organization that owns the stream.
</ResponseField>

<ResponseField name="admin" type="string | null">
  Admin EVM address for the stream when applicable.
</ResponseField>

<ResponseField name="type" type="integer">
  Stream type. Supported values are `1` (`Fixed Rate`), `2` (`Fixed APR`), `3` (`Daily Budget`), `4` (`Airdrop`), and `5` (`Yield Match`).
</ResponseField>

<ResponseField name="createdAt" type="datetime">
  Timestamp when the stream record was created in Turtle's backend.
</ResponseField>

<ResponseField name="updatedAt" type="datetime">
  Timestamp of the most recent update to the stream record.
</ResponseField>

<ResponseField name="startTimestamp" type="datetime">
  UTC start time for the stream.
</ResponseField>

<ResponseField name="endTimestamp" type="datetime | null">
  UTC end time for the stream when configured.
</ResponseField>

<ResponseField name="totalAmount" type="string | null">
  Total reward amount in base units when applicable.
</ResponseField>

<ResponseField name="creationConfirmedAt" type="datetime | null">
  Confirmation timestamp for stream creation. It can be `null` while a token-based stream is still pending on-chain creation.
</ResponseField>

<ResponseField name="snapshotComputationPaused" type="boolean">
  Whether snapshot computation is paused for the stream.
</ResponseField>

<ResponseField name="merkleTreeComputationPaused" type="boolean">
  Whether merkle tree computation is paused for the stream.
</ResponseField>

<ResponseField name="hashCommitmentPaused" type="boolean">
  Whether hash commitment updates are paused for the stream.
</ResponseField>

<ResponseField name="claimPaused" type="boolean">
  Whether claiming rewards is currently paused for the stream.
</ResponseField>

<ResponseField name="customArgs" type="object">
  Strategy-specific configuration object for the stream.
</ResponseField>

<ResponseField name="adapters" type="AdapterConfig[]">
  Persisted adapter configuration array. Each adapter item contains a `type` string and a `params` object.
</ResponseField>

<ResponseField name="point" type="Point | null">
  Point metadata when the stream uses a point-based reward source. `null` for token-based streams.
</ResponseField>

<ResponseField name="strategy" type="string">
  Human-readable strategy name for the stream.
</ResponseField>

<ResponseField name="lastSnapshot" type="StreamSnapshot | null">
  Most recent snapshot computed for the stream, if one exists.
</ResponseField>

<ResponseField name="committedSnapshot" type="StreamSnapshot | null">
  Most recent committed snapshot for the stream, if one exists.
</ResponseField>

<ResponseField name="snapshots" type="StreamSnapshot[]">
  Full snapshot history when `withSnapshots=true`. Otherwise this field can be empty or omitted.
</ResponseField>

<ResponseField name="rewardToken" type="SupportedToken | null">
  Reward-token metadata for token-based streams. This uses the public `SupportedToken` shape from [Get Tokens](/sdk/streams/get-tokens).
</ResponseField>

### `AdapterConfig`

<ResponseField name="type" type="string">
  Adapter type identifier.
</ResponseField>

<ResponseField name="params" type="object">
  Adapter-specific configuration object.
</ResponseField>

### `Point`

See [Get Points](/sdk/streams/get-points) for the full `Point` schema and examples.

### `StreamSnapshot`

APR-related snapshot fields are only populated for token-based streams. For point-based streams, `baseApr`, `apr`, and `rewardTokenPrice` are omitted from the snapshot.

<ResponseField name="timestamp" type="datetime">
  Snapshot timestamp.
</ResponseField>

<ResponseField name="amountDistributed" type="string">
  Amount distributed in the snapshot, encoded as a decimal string.
</ResponseField>

<ResponseField name="amountBase" type="string">
  Base amount used for the snapshot, encoded as a decimal string.
</ResponseField>

<ResponseField name="rootHash" type="string | null">
  Merkle root hash when the snapshot has one.
</ResponseField>

<ResponseField name="commitTxHash" type="string | null">
  Transaction hash of the commit operation when available.
</ResponseField>

<ResponseField name="createdAt" type="datetime">
  Timestamp when the snapshot record was created.
</ResponseField>

<ResponseField name="updatedAt" type="datetime">
  Timestamp of the latest update to the snapshot record.
</ResponseField>

<ResponseField name="tvl" type="string | null">
  Total value locked at snapshot time when available.
</ResponseField>

<ResponseField name="baseTvl" type="string | null">
  Base TVL at snapshot time when available.
</ResponseField>

<ResponseField name="baseApr" type="string | null">
  Base APR computed for the snapshot before adapter adjustments, expressed as a decimal fraction — multiply by 100 for the percentage (for example, `0.05` means 5%). This is only populated for token-based streams.
</ResponseField>

<ResponseField name="apr" type="string | null">
  Effective APR computed for the snapshot after adapter adjustments, expressed as a decimal fraction — multiply by 100 for the percentage (for example, `0.05` means 5%). This is only populated for token-based streams.
</ResponseField>

<ResponseField name="rewardTokenPrice" type="string | null">
  Time-weighted-average (TWA) USD price of the reward token across the snapshot interval. This is only populated for token-based streams.
</ResponseField>

<ResponseField name="customMetrics" type="object">
  Snapshot-specific computed metrics.
</ResponseField>

<ResponseField name="customArgs" type="object">
  Snapshot-specific custom arguments.
</ResponseField>

<ResponseField name="userCount" type="integer | null">
  Number of users represented in the snapshot when `usersCount=true`.
</ResponseField>

<ResponseField name="activeUserCount" type="integer | null">
  Number of active users represented in the snapshot when `usersCount=true`.
</ResponseField>

## Error Handling

<AccordionGroup>
  <Accordion title="Unexpected internal error">
    **Status Code:** 500 Internal Server Error

    **Solution:** Retry the request and contact Turtle if the issue persists.
  </Accordion>
</AccordionGroup>