Python SDK

Integrate webwhen into your Python applications.

Naming during the transition

The package on PyPI is still torale and the client class is still ToraleClient. The rename to webwhen is a later phase — the code samples below use the current shipping names.

Installation

pip install torale

Get an API key

1. Log in to webwhen.ai
2. Go to Settings → API Keys
3. Generate a new key
4. Copy and save it securely

Create your first watch

from torale import ToraleClient

client = ToraleClient(api_key="sk_...")

task = client.tasks.create(
    search_query="When is the iPhone 17 being released?",
    condition_description="Apple has announced a specific release date",
    schedule="0 9 * * *"
)

print(f"Created watch: {task.id}")

Check results

# Execution history
executions = client.tasks.get_executions(task.id)

for execution in executions:
    if execution.notification:
        print(f"Answer: {execution.result['answer']}")
        print(f"Sources: {execution.grounding_sources}")

Environment variables

Store your API key in an environment variable:

export TORALE_API_KEY=sk_...

from torale import ToraleClient

# Client reads the key from the environment automatically
client = ToraleClient()

Async client

For async applications:

from torale import AsyncToraleClient
import asyncio

async def main():
    client = AsyncToraleClient(api_key="sk_...")

    task = await client.tasks.create(
        search_query="When is the iPhone 17 being released?",
        condition_description="Apple has announced a specific release date",
        schedule="0 9 * * *"
    )

    print(f"Created: {task.id}")

asyncio.run(main())

Next steps

• Read the SDK Quickstart for detailed examples
• Learn about the Async Client
• See Error Handling