SOP 003: Basic Query

Fresh 🌱

Document ID: SOP-003
Version: 1.0
Status: Active

Objective

Make your first API call to a Poe bot using the fastapi-poe library.

Prerequisites

• [x] API key obtained (SOP 001)
• [x] fastapi-poe installed (SOP 002)
• Python script ready

Procedure

Step 1: Import Required Modules

import fastapi_poe as fp

Step 2: Set Your API Key

api_key = "your_api_key_here"  # Replace with your actual key

Or from environment variable:

import os
api_key = os.getenv("POE_API_KEY")

Step 3: Create a Message

message = fp.ProtocolMessage(
    role="user",
    content="Hello, how are you?"
)

Step 4: Query a Bot (Synchronous)

for partial in fp.get_bot_response_sync(
    messages=[message],
    bot_name="GPT-5",
    api_key=api_key
):
    print(partial, end="", flush=True)

Step 5: Query a Bot (Asynchronous)

import asyncio

async def get_response():
    async for partial in fp.get_bot_response(
        messages=[message],
        bot_name="GPT-5",
        api_key=api_key
    ):
        print(partial, end="", flush=True)

asyncio.run(get_response())

Complete Example

Synchronous Example

import fastapi_poe as fp
import os

api_key = os.getenv("POE_API_KEY")
message = fp.ProtocolMessage(role="user", content="What is Python?")

print("Querying GPT-5...")
for partial in fp.get_bot_response_sync(
    messages=[message],
    bot_name="GPT-5",
    api_key=api_key
):
    print(partial, end="", flush=True)
print("\n✓ Query complete!")

Asynchronous Example

import asyncio
import fastapi_poe as fp
import os

async def main():
    api_key = os.getenv("POE_API_KEY")
    message = fp.ProtocolMessage(role="user", content="What is Python?")
    
    print("Querying Claude-Sonnet-4.5...")
    async for partial in fp.get_bot_response(
        messages=[message],
        bot_name="Claude-Sonnet-4.5",
        api_key=api_key
    ):
        print(partial, end="", flush=True)
    print("\n✓ Query complete!")

if __name__ == "__main__":
    asyncio.run(main())

Available Bots

Common bot names you can query:

• GPT-5
• Claude-Sonnet-4.5
• Claude-Opus-4.1
• Grok-4
• Imagen-4 (for image generation)

Verification

Expected output:

Querying GPT-5...
[Bot response appears here streaming...]
✓ Query complete!

If you see an error, check:

• API key is correct
• Bot name is spelled correctly
• You have sufficient points
• Rate limit not exceeded

Troubleshooting

Problem: Invalid API key
Solution:

• Verify your API key is correct
• Check for extra spaces
• Ensure environment variable is set

Problem: Bot not found
Solution:

• Check bot name spelling (case-sensitive)
• Verify bot is available on Poe
• Try a different bot name

Problem: Rate limit exceeded
Solution:

• Wait 60 seconds
• Limit is 500 requests/minute
• Implement rate limiting in your code

Problem: Insufficient points
Solution:

• Check your Poe account balance
• Purchase more points if needed

Best Practices

1. Use environment variables for API keys
2. Handle errors gracefully with try/except
3. Implement rate limiting for production
4. Use async for better performance
5. Store conversation history for context

See Also

• SOP 004: Send Files
• SOP 005: Custom Parameters
• Workflow: Query Multiple Bots

---

Next: 004: Send Files