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

# GET /api/threads

> List all available prediction market threads

Fetches a paginated list of all available prediction market threads.

## Endpoint

```
GET https://app.kash.bot/api/threads
```

## Query Parameters

<ParamField query="status" type="string">
  Filter by thread status. Options: `active`, `upcoming`, `completed`, `resolved`, `cancelled`, `paused`
</ParamField>

<ParamField query="category" type="string">
  Filter by category (e.g., `politics`, `crypto`, `sports`)
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated list of tags to filter by (e.g., `election,2024`)
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of results per page (max: 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset for fetching subsequent pages
</ParamField>

<ParamField query="sortBy" type="string" default="created_at">
  Field to sort by. Options: `created_at`, `updated_at`, `total_volume`, `market_count`, `title`
</ParamField>

<ParamField query="sortOrder" type="string" default="desc">
  Sort direction. Options: `asc`, `desc`
</ParamField>

## Response

<ResponseField name="threads" type="array">
  Array of thread objects

  <Expandable title="Thread Object">
    <ResponseField name="id" type="string">
      Unique thread identifier
    </ResponseField>

    <ResponseField name="title" type="string">
      Thread title
    </ResponseField>

    <ResponseField name="description" type="string">
      Thread description (optional)
    </ResponseField>

    <ResponseField name="totalVolume" type="number">
      Total trading volume across all markets in cents
    </ResponseField>

    <ResponseField name="marketCount" type="number">
      Number of markets in this thread
    </ResponseField>

    <ResponseField name="participantCount" type="number">
      Number of unique participants
    </ResponseField>

    <ResponseField name="startTime" type="number">
      Thread start time (Unix timestamp in seconds)
    </ResponseField>

    <ResponseField name="endTime" type="number">
      Thread end time (Unix timestamp in seconds)
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: `active`, `upcoming`, `completed`, `resolved`, `cancelled`, `paused`
    </ResponseField>

    <ResponseField name="category" type="string">
      Thread category
    </ResponseField>

    <ResponseField name="tags" type="array">
      Array of tag strings
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of thread creation
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata

  <Expandable title="Pagination Object">
    <ResponseField name="offset" type="number">
      Current offset
    </ResponseField>

    <ResponseField name="limit" type="number">
      Results per page
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of matching threads
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether more results are available
    </ResponseField>
  </Expandable>
</ResponseField>

## Rate Limit

<Info>
  **50 requests per minute** per IP address
</Info>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.kash.bot/api/threads?status=active&limit=10&sortBy=total_volume&sortOrder=desc"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.kash.bot/api/threads?status=active&limit=10'
  );
  const data = await response.json();
  console.log(`Found ${data.threads.length} active threads`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://app.kash.bot/api/threads',
      params={'status': 'active', 'limit': 10}
  )
  data = response.json()
  print(f"Found {len(data['threads'])} active threads")
  ```
</CodeGroup>

## Example Response

```json 200 - Success theme={null}
{
  "threads": [
    {
      "id": "abc123-def456",
      "title": "2024 Election Predictions",
      "description": "Markets for the 2024 US Presidential Election",
      "totalVolume": 1250000,
      "marketCount": 12,
      "participantCount": 342,
      "startTime": 1704067200,
      "endTime": 1735689600,
      "status": "active",
      "category": "politics",
      "tags": ["election", "politics", "2024"],
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    },
    {
      "id": "xyz789-abc123",
      "title": "Crypto Price Predictions 2024",
      "description": "Will Bitcoin reach $100k?",
      "totalVolume": 980000,
      "marketCount": 8,
      "participantCount": 256,
      "startTime": 1704067200,
      "endTime": 1735689600,
      "status": "active",
      "category": "crypto",
      "tags": ["bitcoin", "crypto", "2024"],
      "createdAt": "2024-01-05T00:00:00Z",
      "updatedAt": "2024-01-16T08:15:00Z"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 25,
    "hasMore": true
  },
  "_meta": {
    "authenticated": false,
    "requestedAt": "2024-01-16T12:00:00Z"
  }
}
```

```json 400 - Bad Request theme={null}
{
  "error": "Invalid query parameters",
  "message": "limit must be between 1 and 100",
  "code": "INVALID_REQUEST"
}
```

```json 429 - Rate Limit Exceeded theme={null}
{
  "error": "Too many requests",
  "message": "Rate limit of 50 requests per minute exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 45
}
```

## Response Headers

All responses include rate limit headers:

```
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067260000
Access-Control-Allow-Origin: *
```

## Common Use Cases

### Fetch active threads with high volume

```bash theme={null}
curl "https://app.kash.bot/api/threads?status=active&sortBy=total_volume&sortOrder=desc&limit=5"
```

### Filter by category and tags

```bash theme={null}
curl "https://app.kash.bot/api/threads?category=politics&tags=election,2024"
```

### Paginate through all threads

```javascript theme={null}
async function fetchAllThreads() {
  let allThreads = [];
  let offset = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://app.kash.bot/api/threads?limit=100&offset=${offset}`
    );
    const data = await response.json();

    allThreads = allThreads.concat(data.threads);
    hasMore = data.pagination.hasMore;
    offset += 100;
  }

  return allThreads;
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="GET /api/threads/:id" href="/developer-docs/public-embed-api/endpoints/thread-detail">
    Get details for a specific thread
  </Card>

  <Card title="GET /api/threads/:id/markets" href="/developer-docs/public-embed-api/endpoints/thread-markets">
    Get all markets in a thread
  </Card>

  <Card title="GET /api/threads/:id/chapters" href="/developer-docs/public-embed-api/endpoints/thread-chapters">
    List chapters within a thread
  </Card>

  <Card title="GET /api/organizations/:id/threads" href="/developer-docs/public-embed-api/endpoints/organization-threads">
    List threads for an organization
  </Card>
</CardGroup>