Skip to main content

adveron

Python client for the Adveron public API — the tenant /v1 surface, generated from the API's own OpenAPI document. Requires Python 3.11+; the transport is httpx.

The client is generated, not hand-written. Every operation, every request shape, and every response model comes from the same registered operations the server dispatches, so the client cannot describe a surface the API does not serve. Beside the generated tree sits a small hand-written layer: a constructor, an error helper, and a cursor loop.

Install

pip install adveron

Authentication

Every call authenticates with a workspace API key as a bearer token. from_env() reads it from the environment and hands back a client every operation accepts:

from adveron import from_env

client = from_env()            # ADVERON_API_KEY, and ADVERON_API_URL if set
Variable Default
ADVERON_API_KEY — required
ADVERON_API_URL https://api.adveron.com optional

Either can be overridden per client, which is what a process serving several workspaces needs:

client = from_env(api_key=key, base_url="https://api.adveron.com", timeout=60.0)

Extra keyword arguments configure the transport. timeout, follow_redirects, headers, cookies, verify and raise_on_unexpected_status are the client's own settings; anything else (transport, proxies, limits, …) reaches httpx.Client unchanged.

The key is passed through exactly as given — it is never parsed, pattern-checked or normalised — and it leaves only as an Authorization: Bearer header, never as a query parameter. Under Managed Agents the environment variable holds an opaque placeholder that the sandbox substitutes for the real credential at egress, so a client that insisted on a key-shaped key would reject every sandboxed run.

Calling an operation

Operations are grouped by tag under adveron.generated.api, one module per operation, named for the operation: brand.mentions.list is brand_mentions_list. Each module offers sync, sync_detailed, asyncio and asyncio_detailed.

from adveron import from_env
from adveron.generated.api.brands import brand_search, brand_get

client = from_env()

found = brand_search.sync(client=client, q="nike", limit=5)
brand = brand_get.sync(found.data.items[0].id, client=client)

sync returns the parsed body: {data, meta} on success, where meta always carries the request_id that also rides the X-Request-Id response header. sync_detailed returns a Response carrying the status and headers as well.

Errors

Operations do not raise on an HTTP status. They return the house error envelope, {"error": {code, message, request_id, details?}}; is_adveron_error tells the two apart:

from adveron import from_env, is_adveron_error
from adveron.generated.api.brands import brand_get

result = brand_get.sync(brand_id, client=client)
if is_adveron_error(result):
    # result.error.code is one of the stable machine codes — e.g.
    # "resource_not_activated", "insufficient_credits", "rate_limited"
    print(result.error.code, result.error.request_id)

AdveronErrorCode is the enum of known codes. Branch with a default arm rather than assuming it is closed: the server can ship a new code before the client is regenerated, and is_adveron_error deliberately accepts one.

Quote request_id in a support request: it joins our logs, traces, and the credit ledger.

Paging

List operations take limit and cursor and answer meta.next_cursor. iter_pages follows it to the end, and iter_items flattens the rows:

from adveron import from_env, iter_items
from adveron.generated.api.audiences import audience_posts

client = from_env()
posts = list(iter_items(audience_posts.sync, "AUD123", client=client, limit=100))

Both take the operation's sync function, its path parameters positionally, and its query parameters as keywords — the same call you would write by hand. max_pages= caps a run; an error envelope on any page raises AdveronError rather than ending the loop quietly, so a 403 can never read as an audience nobody posts in.

Operations that return everything at once (audience_influencers, category_list) carry no cursor and read as a single page, so paging code does not need to know which kind it holds.

One example per group

Brands — search first; every other brand operation takes an id, not a name.

from datetime import date

from adveron.generated.api.brands import brand_search, brand_mentions_list

found = brand_search.sync(client=client, q="nike", limit=5)
mentions = brand_mentions_list.sync(found.data.items[0].id, client=client,
                                    q="running", start_date=date(2026, 5, 1))

Date parameters are typed datetime.date | datetime.datetime, not str — the spec declares them as date-or-date-time and the generated client serialises them.

Categories

from adveron.generated.api.categories import category_list

categories = category_list.sync(client=client)
# categories.data.items[0].subcategories — the launched children under each category

Audiences

from adveron.generated.api.audiences import audience_get

audience = audience_get.sync("AUD123", client=client)

Balance & usage

from adveron.generated.api.billing import balance_get, usage_summary

balance = balance_get.sync(client=client)
usage = usage_summary.sync(client=client, group_by="WORKSPACE")

Metering headers

Successful responses carry X-Credits-Charged / X-Credits-Reason and the organization's purchased throughput as RateLimit-*. Reads answer Cache-Control: no-store. Read them from sync_detailed(...).headers. Pass idempotency_key= to make a call safe to retry — recommended on metered GETs, where an auto-retried read would otherwise double-charge.

Reference

The full operation reference, with request and response shapes for every /v1 endpoint, is the API's own interactive documentation at https://api.adveron.com/v1/docs. The SHA-256 of the exact spec revision this client was generated from ships inside the package as adveron/openapi.sha256.

Metadata

Release files for adveron 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adveron 0.4.0
File Size Uploaded Provenance Actions
adveron-0.4.0.tar.gz 409.3 kB With provenance Details for adveron-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adveron 0.4.0
File Interpreter ABI Platform Actions
adveron-0.4.0-py3-none-any.whl Python 3 none any Details for adveron-0.4.0-py3-none-any.whl

Total release size: 1.8 MB

Release files / adveron-0.4.0.tar.gz

Download URL adveron-0.4.0.tar.gz
Size 409.3 kB
Tags Source
SHA-256 checksum
How to use checksums
17c90f30170935156438fc2eaf8f118a619dd3446f96ee13361d4886e61f0db0
BLAKE2b-256 checksum
How to use checksums
34564a20df3b122e6afc3e83821e1429bf7a26724755efbbfe183afe3d5e95e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.

Transparency log

Release files / adveron-0.4.0-py3-none-any.whl

Download URL adveron-0.4.0-py3-none-any.whl
Size 1.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
743af9742a78b0d03855975fccf0b40ebbfb36a920d57e2efb588bd98b7e1dbe
BLAKE2b-256 checksum
How to use checksums
6f5afccfe5577685a8ff27637f2ab08bec67028c5ccef530e3fe26aa0bb61891
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.

Transparency log

Security for adveron 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for adveron-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.4.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page