The sync client (Olostep) provides a blocking interface that’s perfect for scripts and simple use cases.
from olostep import Olostep# Provide the API key either via passing in the 'api_key' parameter or# by setting the OLOSTEP_API_KEY environment variable# The sync client handles resource management automatically# No explicit close needed - resources are cleaned up after each operationclient = Olostep(api_key="YOUR_REAL_KEY")scrape_result = client.scrapes.create(url_to_scrape="https://example.com")
from olostep import Olostepclient = Olostep(api_key="your-api-key")# Extract all links from a websitemaps = client.maps.create(url="https://example.com")# Get all discovered URLsurls = []for url in maps.urls(): urls.append(url) if len(urls) >= 10: # Limit for demo breakprint(f"Found {len(urls)} URLs")
from olostep import Olostepclient = Olostep(api_key="your-api-key")# Get answers from web pages using AIanswer = client.answers.create( task="What is the main topic of https://example.com?")print(f"Answer: {answer.answer}")
The async client (AsyncOlostep) is the recommended client for high-performance applications, backend services, and when you need to handle many concurrent requests.
from olostep import AsyncOlostep# Provide the API key either via passing in the 'api_key' parameter or# by setting the OLOSTEP_API_KEY environment variable# RESOURCE MANAGEMENT# ===================# The SDK supports two usage patterns for resource management:# 1. Context Manager (Recommended for one-off usage):# Automatically handles resource cleanupasync with AsyncOlostep(api_key="YOUR_REAL_KEY") as client: scrape_result = await client.scrapes.create(url_to_scrape="https://example.com")# Transport is automatically closed here# 2. Explicit Close (For long-lived services):# Requires manual resource cleanupclient = AsyncOlostep(api_key="YOUR_REAL_KEY")try: scrape_result = await client.scrapes.create(url_to_scrape="https://example.com")finally: await client.close() # Manually close the transport
import asynciofrom olostep import AsyncOlostepasync def main(): async with AsyncOlostep(api_key="your-api-key") as client: # Extract all links from a website maps = await client.maps.create(url="https://example.com") # Get all discovered URLs urls = [] async for url in maps.urls(): urls.append(url) if len(urls) >= 10: # Limit for demo break print(f"Found {len(urls)} URLs")asyncio.run(main())
import asynciofrom olostep import AsyncOlostepasync def main(): async with AsyncOlostep(api_key="your-api-key") as client: # Get answers from web pages using AI answer = await client.answers.create( task="What is the main topic of https://example.com?" ) print(f"Answer: {answer.answer}")asyncio.run(main())
Catch all SDK errors using the base exception class:
from olostep import Olostep, Olostep_BaseErrorclient = Olostep(api_key="your-api-key")try: result = client.scrapes.create(url_to_scrape="https://example.com")except Olostep_BaseError as e: print(f"Error has occurred: {type(e).__name__}") print(f"Error message: {e}")
For detailed error handling information, including the full exception hierarchy and granular error handling options, see Detailed Error Handling.
The SDK automatically retries on transient errors (network issues, temporary server problems) based on the RetryStrategy configuration. You can customize the retry behavior by passing a RetryStrategy instance when creating the client:
from olostep import Olostepclient = Olostep(api_key="your-api-key")# First create an answercreated_answer = client.answers.create( task="What is the main topic of https://example.com?")# Then retrieve it using the IDanswer = client.answers.get(answer_id=created_answer.id)print(f"Answer: {answer.answer}")
The RetryStrategy class controls how the Olostep SDK handles transient API errors through automatic retries with exponential backoff and jitter. This helps ensure reliable operation in production environments where temporary network issues, rate limits, and server overload can cause intermittent failures.
When all retries are exhausted, the original error is raised:
try: result = await client.scrapes.create("https://example.com")except OlostepServerError_TemporaryIssue as e: print(f"Failed after all retries: {e}") # Handle the permanent failure
The Olostep SDK provides a comprehensive exception hierarchy for different failure scenarios. All exceptions inherit from Olostep_BaseError.There are three main error types that directly inherit from Olostep_BaseError:
Olostep_APIConnectionError is separate from server errors because it represents network-level failures that occur before the API can process the request. These are transport layer issues (DNS or HTTP failures, timeouts, connection refused, etc.) rather than API-level errors. HTTP status codes (4xx, 5xx) are considered API responses and are categorized as server errors, even though they indicate problems.
For most use cases, catch the base error and print the error name:
from olostep import AsyncOlostep, Olostep_BaseErrortry: result = await client.scrapes.create(url_to_scrape="https://example.com")except Olostep_BaseError as e: print(f"Error has occurred: {type(e).__name__}") print(f"Error message: {e}")
This approach catches all SDK errors and provides clear information about what went wrong. The error name (e.g., OlostepServerError_AuthFailed) is descriptive enough to understand the issue.
If you need more specific error handling, catch the specific error types directly. Avoid using OlostepServerError_BaseError or OlostepClientError_BaseError - these base classes only indicate who raised the error (server vs client), not who’s responsible for fixing it. This is an implementation detail that doesn’t help with error handling logic.Instead, catch specific error types that indicate the actual problem:
from olostep import ( AsyncOlostep, Olostep_BaseError, Olostep_APIConnectionError, OlostepServerError_AuthFailed, OlostepServerError_CreditsExhausted, OlostepClientError_NoAPIKey,)try: result = await client.scrapes.create(url_to_scrape="https://example.com")except Olostep_APIConnectionError as e: print(f"Network error: {type(e).__name__}")except OlostepServerError_AuthFailed: print("Invalid API key")except OlostepServerError_CreditsExhausted: print("Credits exhausted")except OlostepClientError_NoAPIKey: print("API key not provided")except Olostep_BaseError as e: print(f"Error has occurred: {type(e).__name__}")
