List Prompts

Retrieve and filter prompts with pagination support

Overview

The list() method allows you to retrieve prompts with optional filtering and pagination. This is useful for browsing, searching, and managing your prompt collection.

Usage example

from keywordsai.prompts.api import PromptAPI
import asyncio
import os
from dotenv import load_dotenv

load_dotenv(override=True)

# Create the client
client = PromptAPI(
    api_key=os.getenv("KEYWORDS_AI_API_KEY"),
    base_url=os.getenv("KEYWORDS_AI_BASE_URL")
)

# Synchronous example
response = client.list()
print(f"Total prompts: {response.count}")

for prompt in response.results:
    print(f"- {prompt.name} (ID: {prompt.prompt_id})")

# Asynchronous example
async def list_prompts_async():
    response = await client.alist()
    print(f"Total prompts: {response.count}")
    
    for prompt in response.results:
        print(f"- {prompt.name} (ID: {prompt.prompt_id})")

# Run the async function
asyncio.run(list_prompts_async())

Parameters

page · integer · default: 1

Page number for pagination.

page_size · integer · default: 50

Number of prompts per page (max 100).

name · string

Filter by prompt name (partial match).

metadata · object

Filter by metadata key-value pairs.

sort_by · string

Field to sort by (name, created_at, updated_at).

sort_order · string

Sort order (asc, desc).

Returns

Returns a PromptListResponse object containing the list of prompts and pagination information:

PromptListResponse(
    count=3,
    next="http://api.keywordsai.co/api/prompts/list?page=2",
    previous=None,
    results=[
        Prompt(
            prompt_id="fa51377c8e8d42e1ad54c5864f2cd201",
            name="20games",
            description="",
            live_version=10883,
            created_at="2024-01-15T10:30:00Z",
            updated_at="2024-01-20T14:45:00Z"
        )
    ]
)

Examples

Basic Synchronous Example

import os
from dotenv import load_dotenv
from keywordsai.prompts.api import PromptAPI

load_dotenv()

def list_prompts_sync():
    """Basic synchronous prompt listing"""
    api_key = os.getenv("KEYWORDS_AI_API_KEY")
    base_url = os.getenv("KEYWORDS_AI_BASE_URL")
    client = PromptAPI(api_key=api_key, base_url=base_url)
    
    try:
        response = client.list()
        print(f"✓ Found {response.count} prompts")
        
        for prompt in response.results:
            print(f"  - {prompt.name} (ID: {prompt.prompt_id})")
        
        return response
    except Exception as e:
        print(f"✗ Error: {e}")
        return None

# Usage
list_prompts_sync()

With Pagination

def list_prompts_with_pagination():
    """List prompts with pagination"""
    client = PromptAPI(
        api_key=os.getenv("KEYWORDS_AI_API_KEY"),
        base_url=os.getenv("KEYWORDS_AI_BASE_URL")
    )
    
    # Get first page with 10 prompts
    response = client.list(page=1, page_size=10)
    
    print(f"Page 1: {len(response.results)} of {response.count} prompts")
    
    for prompt in response.results:
        print(f"  - {prompt.name}")
    
    # Check if there's a next page
    if response.next:
        print(f"Next page available: {response.next}")

# Usage
list_prompts_with_pagination()

With Filtering

def list_prompts_with_filter():
    """List prompts with name filtering"""
    client = PromptAPI(
        api_key=os.getenv("KEYWORDS_AI_API_KEY"),
        base_url=os.getenv("KEYWORDS_AI_BASE_URL")
    )
    
    # Filter prompts by name
    response = client.list(name="game", page_size=20)
    
    print(f"Found {response.count} prompts matching 'game'")
    
    for prompt in response.results:
        print(f"  - {prompt.name} (Live Version: {prompt.live_version})")
        if prompt.description:
            print(f"    Description: {prompt.description}")

# Usage
list_prompts_with_filter()

Asynchronous Example

import asyncio
import os
from dotenv import load_dotenv
from keywordsai.prompts.api import PromptAPI

load_dotenv()

async def list_prompts_async():
    """Asynchronous prompt listing"""
    api_key = os.getenv("KEYWORDS_AI_API_KEY")
    base_url = os.getenv("KEYWORDS_AI_BASE_URL")
    client = PromptAPI(api_key=api_key, base_url=base_url)
    
    try:
        response = await client.alist(page_size=20)
        print(f"✓ Async: Found {response.count} prompts")
        
        for prompt in response.results:
            print(f"  - {prompt.name} (Live Version: {prompt.live_version})")
        
        return response
    except Exception as e:
        print(f"✗ Async error: {e}")
        return None

# Usage
asyncio.run(list_prompts_async())

Asynchronous with Filtering

async def list_prompts_async_filtered():
    """Asynchronous prompt listing with filtering"""
    client = PromptAPI(
        api_key=os.getenv("KEYWORDS_AI_API_KEY"),
        base_url=os.getenv("KEYWORDS_AI_BASE_URL")
    )
    
    try:
        # Filter and sort prompts
        response = await client.alist(
            name="test",
            sort_by="created_at",
            sort_order="desc",
            page_size=10
        )
        
        print(f"✓ Found {response.count} prompts matching 'test'")
        
        for prompt in response.results:
            print(f"  - {prompt.name}")
            print(f"    ID: {prompt.prompt_id}")
            print(f"    Created: {prompt.created_at}")
            print(f"    Live Version: {prompt.live_version}")
            print()
        
        return response
    except Exception as e:
        print(f"✗ Error: {e}")
        return None

# Usage
asyncio.run(list_prompts_async_filtered())

Convenience Functions

You can also use the convenience function to create a PromptAPI client:

from keywordsai import create_prompt_client

client = create_prompt_client(api_key="your-api-key")
response = client.list()
print(f"Found {response.count} prompts")

for prompt in response.results:
    print(f"- {prompt.name}")