AsyncGrill Client API Reference

from poma import AsyncGrill

AsyncGrill is the asyncio counterpart to Grill. The surface area is identical — every method has the same name, the same parameters, and the same return type. The only difference is that ingest, search, and document calls are await-able and the constructor takes an httpx.AsyncClient.

Use AsyncGrill inside web servers, agents, and pipelines that already run under an event loop. For scripts and notebooks, Grill is simpler.

Constructor

AsyncGrill(
    api_key: str | None = None,
    *,
    timeout: float = 600.0,
    client: httpx.AsyncClient | None = None,
)

Same semantics as Grill(...). Reads POMA_GRILL_API_KEY if api_key is omitted; raises InvalidGrillApiKeyError on a bad prefix before any HTTP traffic.

Methods

Every method on Grill is mirrored as async:

Sync (Grill)	Async (AsyncGrill)
submit(file_path, *, base_url=None) -> str	await submit(...) -> str
collect(job_id, ...) -> GrillIngestResult	await collect(...) -> GrillIngestResult
ingest(file_path, ...) -> GrillIngestResult	await ingest(...) -> GrillIngestResult
search(query, ...) -> GrillContext	await search(...) -> GrillContext
search_in_doc(query, doc_filter, ...) -> GrillContext	await search_in_doc(...) -> GrillContext
list_docs() -> list[DocInfo]	await list_docs() -> list[DocInfo]
get_doc(doc_id) -> DocInfo	await get_doc(doc_id) -> DocInfo
delete_doc(doc_id) -> DeleteDocResponse	await delete_doc(doc_id) -> DeleteDocResponse
close() -> None	await aclose() -> None

Parameter semantics and validation behaviour are identical to the sync client — see Grill for the per-method tables.

Lifecycle

Use as an async context manager so the underlying httpx.AsyncClient is closed automatically:

import asyncio
from poma import AsyncGrill

async def main() -> None:
    async with AsyncGrill() as g:
        result = await g.ingest("annual-report.pdf")
        ctx = await g.search(
            "How did operating margin change year over year?",
            max_tokens=4000,
        )
        print(result.job_id, result.status)
        print(ctx.context)

asyncio.run(main())

If you need to keep the client open across multiple unrelated request scopes (e.g. a long-lived web server), instantiate once and call await g.aclose() on shutdown.

Exceptions

Identical to Grill — InvalidGrillApiKeyError, ApiError, InvalidResponseError. See Exceptions.

See also

• Grill — sync client with per-method tables.
• Grill concept page — workflow walkthrough.
• Grill product docs — endpoint-level reference, RetrievalContext format, billing.