Source: http://www.poma-ai.com/docs/sdk/reference/async-grill

# AsyncGrill Client API Reference

```python
from poma import AsyncGrill
```

`AsyncGrill` is the `asyncio` counterpart to [`Grill`](/sdk/reference/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`](/sdk/reference/grill) is simpler.

## Constructor

```python
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`](/sdk/reference/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`](/sdk/reference/grill) for the per-method tables.

## Lifecycle

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

```python
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?")
        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](/sdk/reference/exceptions).

## See also

- [`Grill`](/sdk/reference/grill) — sync client with per-method tables.
- [Grill concept page](/sdk/concepts/grill) — workflow walkthrough.
- [Grill product docs](/grill/) — endpoint-level reference, RetrievalContext format, billing.