> ## 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 all streams for the calling organization, or filter by a specific stream ID

<Note>
  All requests require an API key via the `X-API-Key` header.
  See [Authentication](/sdk/authentication/api-keys) for details.
</Note>

## Overview

`GET /v1/streams/` returns streams scoped to the organization that owns the API key used in the request.

* If no `id` query parameter is sent, the endpoint returns all confirmed streams for that organization.
* If `id` is sent, the endpoint returns at most one stream: the stream whose identifier matches the provided value and belongs to the calling organization.

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

<Info>
  This endpoint is organization-scoped by design. It does not return streams belonging to other organizations, even if their IDs are known.
</Info>

## Endpoint

### Get all streams for the calling organization

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

  ```typescript TypeScript theme={null}
  const response = await fetch(
    'https://earn.turtle.xyz/v1/streams/?withSnapshots=false&usersCount=false',
    {
      headers: { 'X-API-Key': process.env.TURTLE_SECRET_KEY! },
    }
  );

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

### Get one stream by ID within the organization scope

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

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

  const response = await fetch(
    `https://earn.turtle.xyz/v1/streams/?id=${streamId}&withSnapshots=true&usersCount=true`,
    {
      headers: { 'X-API-Key': process.env.TURTLE_SECRET_KEY! },
    }
  );

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

**Query Parameters**

<ParamField query="id" type="uuid">
  Optional stream identifier. When provided, the endpoint filters the organization-scoped result set to that stream ID.
</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",
        "netTvl": "149100.20",
        "turtleTvl": "152340.12",
        "turtleNetTvl": "149100.20",
        "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 id means list all streams for the organization">
    If you omit `id`, the endpoint returns all confirmed streams belonging to the organization associated with the API key.
  </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 the stream does not exist in the caller's organization scope.
  </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 streams visible to the organization that owns the API key.
</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`), and `3` (`Variable Rate`).
</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="netTvl" type="string | null">
  Net TVL at snapshot time when available.
</ResponseField>

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

<ResponseField name="turtleNetTvl" type="string | null">
  Turtle net TVL at snapshot time when available.
</ResponseField>

<ResponseField name="baseApr" type="string | null">
  Base APR computed for the snapshot before adapter adjustments. This is only populated for token-based streams.
</ResponseField>

<ResponseField name="apr" type="string | null">
  Effective APR computed for the snapshot after adapter adjustments. 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="Missing or invalid API key">
    **Status Code:** 401 Unauthorized

    ```json theme={null}
    {
      "error": "Invalid API key"
    }
    ```

    **Solution:** Pass a valid `X-API-Key` header belonging to an organization-scoped API key.
  </Accordion>

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

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