Listing and Pagination

Learn how to list prompts in your workspace and paginate through large result sets.

Listing Prompts

Use the list_prompts() method to browse prompts:

from baytos.claro import BaytClient

client = BaytClient(api_key="your_api_key")

# Get first page of prompts
result = client.list_prompts(limit=20)

# Access prompts
for prompt in result['prompts']:
    print(f"{prompt.title} - {prompt.package_name}")

Response Format

The list_prompts() method returns a dictionary:

{
    'prompts': [Prompt, Prompt, ...],  # List of Prompt objects
    'cursor': 'abc123...',              # Cursor for next page
    'hasMore': True                     # True if more pages available
}

Accessing Results

result = client.list_prompts(limit=10)

# Get prompts
prompts = result['prompts']
print(f"Retrieved {len(prompts)} prompts")

# Check pagination
if result['hasMore']:
    print("More pages available")
    next_cursor = result['cursor']

# Access prompt details
for prompt in prompts:
    print(f"Title: {prompt.title}")
    print(f"Package: {prompt.package_name}")
    print(f"Version: {prompt.version}")
    print()

Pagination

Basic Pagination

Use the cursor parameter to fetch subsequent pages:

client = BaytClient(api_key="your_api_key")

# First page
page1 = client.list_prompts(limit=20)

# Second page
if page1['hasMore']:
    page2 = client.list_prompts(limit=20, cursor=page1['cursor'])

# Third page
if page2['hasMore']:
    page3 = client.list_prompts(limit=20, cursor=page2['cursor'])

Iterating Through All Pages

def get_all_prompts(client):
    """Get all prompts across all pages"""
    all_prompts = []
    cursor = None

    while True:
        # Fetch page
        result = client.list_prompts(limit=100, cursor=cursor)

        # Add prompts to list
        all_prompts.extend(result['prompts'])

        # Check if more pages exist
        if not result['hasMore']:
            break

        # Get cursor for next page
        cursor = result['cursor']

    return all_prompts

# Usage
client = BaytClient(api_key="...")
prompts = get_all_prompts(client)
print(f"Total prompts: {len(prompts)}")

Pagination with Limit

Control how many results to fetch:

def get_prompts_with_limit(client, max_count=1000):
    """Get prompts up to a maximum count"""
    prompts = []
    cursor = None

    while len(prompts) < max_count:
        # Calculate how many to fetch
        remaining = max_count - len(prompts)
        limit = min(remaining, 100)

        # Fetch page
        result = client.list_prompts(limit=limit, cursor=cursor)

        # Add prompts
        prompts.extend(result['prompts'])

        # Check if done
        if not result['hasMore']:
            break

        cursor = result['cursor']

    return prompts[:max_count]

# Usage
prompts = get_prompts_with_limit(client, max_count=500)

Limit Parameter

Control page size with the limit parameter:

# Small pages (faster response, more requests)
result = client.list_prompts(limit=10)

# Medium pages (balanced)
result = client.list_prompts(limit=50)

# Large pages (fewer requests, slower response)
result = client.list_prompts(limit=100)

The limit parameter must be between 1 and 100. Default is 20.

Validation

from baytos.claro import BaytValidationError

try:
    # Too small
    result = client.list_prompts(limit=0)
except BaytValidationError:
    print("Limit must be at least 1")

try:
    # Too large
    result = client.list_prompts(limit=200)
except BaytValidationError:
    print("Limit cannot exceed 100")

Complete Examples

Example 1: Display All Prompts

#!/usr/bin/env python3
"""
List all prompts in your workspace
"""

import os
from baytos.claro import BaytClient

def list_all_prompts():
    client = BaytClient(api_key=os.getenv("BAYT_API_KEY"))

    print("Your Prompts:")
    print("=" * 70)

    cursor = None
    total = 0

    while True:
        # Fetch page
        result = client.list_prompts(limit=50, cursor=cursor)

        # Display prompts
        for prompt in result['prompts']:
            total += 1
            print(f"{total}. {prompt.title}")
            print(f"   Package: {prompt.package_name}")

            if prompt.description:
                print(f"   Description: {prompt.description}")

            # Show if has context
            if prompt.has_context():
                file_count = len(prompt.get_file_contexts())
                url_count = len(prompt.get_url_contexts())
                print(f"   Context: {file_count} files, {url_count} URLs")

            print()

        # Check for more pages
        if not result['hasMore']:
            break

        cursor = result['cursor']

    print(f"\nTotal: {total} prompt(s)")

if __name__ == "__main__":
    list_all_prompts()

Example 2: Search and Filter

#!/usr/bin/env python3
"""
Search for prompts by title
"""

import os
from baytos.claro import BaytClient

def search_prompts(search_term: str):
    """Find prompts matching search term"""
    client = BaytClient(api_key=os.getenv("BAYT_API_KEY"))

    matching = []
    cursor = None

    print(f"Searching for: '{search_term}'\n")

    while True:
        result = client.list_prompts(limit=100, cursor=cursor)

        # Filter by title
        for prompt in result['prompts']:
            if search_term.lower() in prompt.title.lower():
                matching.append(prompt)

        if not result['hasMore']:
            break

        cursor = result['cursor']

    # Display results
    print(f"Found {len(matching)} matching prompt(s):\n")
    for i, prompt in enumerate(matching, 1):
        print(f"{i}. {prompt.title}")
        print(f"   {prompt.package_name}")
        print()

    return matching

if __name__ == "__main__":
    import sys

    search_term = sys.argv[1] if len(sys.argv) > 1 else "support"
    search_prompts(search_term)

Example 3: Export to CSV

#!/usr/bin/env python3
"""
Export all prompts to CSV
"""

import os
import csv
from baytos.claro import BaytClient

def export_prompts_to_csv(filename: str = "prompts.csv"):
    """Export all prompts to a CSV file"""
    client = BaytClient(api_key=os.getenv("BAYT_API_KEY"))

    with open(filename, 'w', newline='', encoding='utf-8') as csvfile:
        writer = csv.writer(csvfile)

        # Header
        writer.writerow([
            'Title',
            'Package Name',
            'Version',
            'Description',
            'Has Context',
            'File Count',
            'URL Count'
        ])

        # Fetch all prompts
        cursor = None
        total = 0

        while True:
            result = client.list_prompts(limit=100, cursor=cursor)

            for prompt in result['prompts']:
                total += 1

                writer.writerow([
                    prompt.title,
                    prompt.package_name,
                    prompt.version,
                    prompt.description or '',
                    'Yes' if prompt.has_context() else 'No',
                    len(prompt.get_file_contexts()),
                    len(prompt.get_url_contexts())
                ])

            if not result['hasMore']:
                break

            cursor = result['cursor']

    print(f"Exported {total} prompts to {filename}")

if __name__ == "__main__":
    export_prompts_to_csv()

Generator Pattern

Use a generator for memory-efficient iteration:

def iter_prompts(client, limit=100):
    """Generator that yields prompts one at a time"""
    cursor = None

    while True:
        result = client.list_prompts(limit=limit, cursor=cursor)

        # Yield each prompt
        for prompt in result['prompts']:
            yield prompt

        # Check if done
        if not result['hasMore']:
            break

        cursor = result['cursor']

# Usage - memory efficient for large result sets
client = BaytClient(api_key="...")

for prompt in iter_prompts(client):
    print(f"Processing: {prompt.title}")
    # Process one at a time without loading all into memory

Best Practices

Choose Appropriate Page Sizes

Balance between request count and response time:

# ✅ Good: Reasonable page size
result = client.list_prompts(limit=50)

# ❌ Too small: Many requests
result = client.list_prompts(limit=5)

# ❌ Too large: May be slower
result = client.list_prompts(limit=100)  # Only if needed

Use larger pages for batch processing, smaller pages for interactive displays.

Handle Empty Results

Always check if results are empty:

result = client.list_prompts(limit=20)

if not result['prompts']:
    print("No prompts found")
else:
    for prompt in result['prompts']:
        print(prompt.title)

Implement Progress Tracking

Show progress when fetching many pages:

def get_all_prompts_with_progress(client):
    all_prompts = []
    cursor = None
    page = 0

    while True:
        page += 1
        print(f"Fetching page {page}...", end='\r')

        result = client.list_prompts(limit=100, cursor=cursor)
        all_prompts.extend(result['prompts'])

        if not result['hasMore']:
            break

        cursor = result['cursor']

    print(f"\nFetched {len(all_prompts)} prompts across {page} pages")
    return all_prompts

Cache Results When Appropriate

Cache results for repeated access:

from functools import lru_cache
from datetime import datetime, timedelta

class PromptCache:
    def __init__(self, client, ttl_seconds=300):
        self.client = client
        self.cache = None
        self.cache_time = None
        self.ttl = timedelta(seconds=ttl_seconds)

    def get_prompts(self):
        now = datetime.now()

        # Check if cache is valid
        if (self.cache is None or
            self.cache_time is None or
            now - self.cache_time > self.ttl):

            # Refresh cache
            self.cache = get_all_prompts(self.client)
            self.cache_time = now

        return self.cache

# Usage
cache = PromptCache(client, ttl_seconds=300)
prompts = cache.get_prompts()  # First call - fetches from API
prompts = cache.get_prompts()  # Second call - returns cached

Error Handling

Handle errors when listing prompts:

from baytos.claro import BaytClient, BaytAuthError, BaytAPIError

client = BaytClient(api_key="...")

try:
    result = client.list_prompts(limit=20)

    for prompt in result['prompts']:
        print(prompt.title)

except BaytAuthError:
    print("Authentication failed - check your API key")
except BaytAPIError as e:
    print(f"API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Next Steps

Working with Prompts

Learn about prompt content and metadata

Error Handling

Handle errors gracefully

Advanced Features

Performance optimization techniques

API Reference

Complete API documentation

Getting Started

Python SDK

Examples

Guides

Listing and Pagination

Listing Prompts

Response Format

Accessing Results

Iterating Through All Pages

Limit Parameter

Validation

Complete Examples

Example 1: Display All Prompts

Example 2: Search and Filter

Example 3: Export to CSV

Generator Pattern

Best Practices

Error Handling

Next Steps

Working with Prompts

Error Handling

Advanced Features

API Reference

​Listing and Pagination

​Listing Prompts

​Response Format

​Accessing Results

​Pagination

​Basic Pagination

​Iterating Through All Pages

​Pagination with Limit

​Limit Parameter

​Validation

​Complete Examples

​Example 1: Display All Prompts

​Example 2: Search and Filter

​Example 3: Export to CSV

​Generator Pattern

​Best Practices

​Error Handling

​Next Steps

Working with Prompts

Error Handling

Advanced Features

API Reference

Listing and Pagination

Listing Prompts

Response Format

Accessing Results

Pagination

Basic Pagination

Iterating Through All Pages

Pagination with Limit

Limit Parameter

Validation

Complete Examples

Example 1: Display All Prompts

Example 2: Search and Filter

Example 3: Export to CSV

Generator Pattern

Best Practices

Error Handling

Next Steps