Python

The official Python SDK for Piloterr, with one typed method per endpoint and a generic request() for anything else.

RequirementsCopy Anchor Link

• Python 3.11+

InstallCopy Anchor Link

pip install piloterr

Get your API keyCopy Anchor Link

Copy your API key from the Piloterr dashboard and set it in the PILOTERR_API_KEY environment variable, which the SDK reads by default. Keep it out of source control.

Quick startCopy Anchor Link

import os

from piloterr import PiloterrClient

with PiloterrClient(os.environ["PILOTERR_API_KEY"]) as client:
    response = client.amazon_product(query="B09DFCB66S")
    print(response.data)

Async jobsCopy Anchor Link

Any call accepts is_async, which is useful past the 60-second server limit. The response is then a job_id, and the SDK can wait for the job to finish.

submitted = client.amazon_product(query="B09DFCB66S", is_async=True)
job = client.wait_for_job(
    submitted.data["job_id"],
    on_progress=lambda j: print(j["status"], j.get("progress")),
)
print(job.data)

ErrorsCopy Anchor Link

A non-2xx response raises an API error with its status and message. See Status codes for the full list.

from piloterr import PiloterrAPIError

try:
    client.amazon_product(query="B09DFCB66S")
except PiloterrAPIError as error:
    print(error.status, error, error.response_body)

RetriesCopy Anchor Link

Requests are retried up to 3 times after a network error, a 408, 500, 502, 503 or 504, or a plan rate limit. Per-key quota errors and client-side timeouts are not retried. The delay starts at 1 second and grows 1.5× per retry, and a Retry-After header wins.

client = PiloterrClient(max_retries=5, retry_delay=0.5)

# or for one request
client.amazon_product(query="B09DFCB66S", request_options=RequestOptions(max_retries=0))

Batch requestsCopy Anchor Link

Run many calls at once, 10 at a time by default. One failure does not stop the others.

inputs = ["B09DFCB66S", "B0BSHF7WHW", "B08N5WRWNW"]
results = client.batch(inputs, lambda query: client.amazon_product(query=query), concurrency=5)

for result in results:
    if result.ok:
        print(result.value.data)
    else:
        print(inputs[result.index], result.error)

Any endpointCopy Anchor Link

request() reaches any path, including endpoints released after your SDK version.

response = client.request("GET", "/v1/usage")

Common mistakesCopy Anchor Link

• Putting the API key in front-end code. Anyone could read it. Call the API from your server.
• Treating every 401 as a bad key. A 401 can also be a rate limit: read the message. The SDK retries plan rate limits for you.
• Retrying a 402. It means there are no credits or quota left, so a retry cannot succeed. See Credits.
• Waiting on long requests. Past 60 seconds, use async mode as shown above rather than raising your timeout. See Timeout.

LinksCopy Anchor Link

• Package: piloterr
• Source code: github.com/piloterr/piloterr-python
• API reference