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

# Pagination

> Handle large datasets with cursor-based pagination

Most list endpoints support cursor-based pagination for fetching large datasets efficiently.

## How Cursor Pagination Works

<Steps>
  <Step title="Initial Request">
    Make your initial request without a cursor
  </Step>

  <Step title="Check Response">
    The response includes a `cursor` and `has_more` flag
  </Step>

  <Step title="Next Page">
    If `has_more` is `true`, use the cursor in your next request
  </Step>

  <Step title="Repeat">
    Continue until `has_more` is `false`
  </Step>
</Steps>

## Example: Paginating TikTok Posts

### Initial Request

```bash theme={null}
curl -X POST "https://data-api.deepdiveplatform.com/api/v1/tiktok/posts" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "charlidamelio",
    "limit": 10
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "posts": [...],
    "cursor": "1705315800000",
    "has_more": true
  },
  "metadata": {
    "credits_used": 11
  }
}
```

### Next Page Request

```bash theme={null}
curl -X POST "https://data-api.deepdiveplatform.com/api/v1/tiktok/posts" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "charlidamelio",
    "limit": 10,
    "cursor": "1705315800000"
  }'
```

## Code Examples

<CodeGroup>
  ```python Python theme={null}
  import requests

  def fetch_all_posts(username, max_posts=100):
      all_posts = []
      cursor = None

      while len(all_posts) < max_posts:
          payload = {
              "username": username,
              "limit": min(100, max_posts - len(all_posts))
          }
          if cursor:
              payload["cursor"] = cursor

          response = requests.post(
              "https://data-api.deepdiveplatform.com/api/v1/tiktok/posts",
              headers={"X-API-Key": "your-api-key"},
              json=payload
          )

          data = response.json()
          posts = data["data"]["posts"]
          all_posts.extend(posts)

          if not data["data"]["has_more"]:
              break

          cursor = data["data"]["cursor"]

      return all_posts
  ```

  ```javascript JavaScript theme={null}
  async function fetchAllPosts(username, maxPosts = 100) {
    const allPosts = [];
    let cursor = null;

    while (allPosts.length < maxPosts) {
      const payload = {
        username,
        limit: Math.min(100, maxPosts - allPosts.length)
      };
      if (cursor) {
        payload.cursor = cursor;
      }

      const response = await fetch("https://data-api.deepdiveplatform.com/api/v1/tiktok/posts", {
        method: "POST",
        headers: {
          "X-API-Key": "your-api-key",
          "Content-Type": "application/json"
        },
        body: JSON.stringify(payload)
      });

      const data = await response.json();
      allPosts.push(...data.data.posts);

      if (!data.data.has_more) break;
      cursor = data.data.cursor;
    }

    return allPosts;
  }
  ```
</CodeGroup>

## Endpoints with Pagination

| Endpoint                  | Cursor Field       | Max Limit |
| ------------------------- | ------------------ | --------- |
| `/tiktok/posts`           | `cursor`           | 100       |
| `/instagram/posts`        | `cursor`           | 100       |
| `/reddit/posts`           | `cursor`           | 100       |
| `/youtube/channel/videos` | N/A (uses `depth`) | 50        |

## Important Notes

<Warning>
  Cursors are opaque strings - don't try to parse or modify them
</Warning>

<Note>
  Cursors may expire after some time. If you get an error, start from the beginning.
</Note>

* The `limit` parameter controls how many items per page (not total)
* Credit costs apply to each paginated request