> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gc.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Async and polling

> How gcai handles long-running work: chat and playbook runs wait for the result by default, with flags to return early or bound the wait.

Some operations run a model and take a while: `gcai chat create` and `gcai playbooks run`. The CLI handles the waiting for you.

## Wait by default

`chat create` and `playbooks run` submit the job, poll it to completion, and print the finished result. You do not need to run a separate poll loop. If the job ends in an error, the command exits non-zero with the error message.

```bash theme={null}
# Blocks until the answer is ready, then prints it
gcai chat create "Draft a mutual NDA" --playbook-ids <id>
```

Two flags control the wait:

| Flag                  | Effect                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------- |
| `--async`             | Return the pending job immediately instead of waiting. You get a `job_id` to poll yourself. |
| `--timeout <seconds>` | Bound the client-side wait before giving up (default 300).                                  |

## Polling a job yourself

If you used `--async` (or want to check on a job later), poll it with `jobs get`:

```bash theme={null}
gcai chat create "…" --async          # returns { job_id, status: "pending", … }
gcai jobs get <job_id> --wait 30       # server long-polls up to 30s, then returns
```

`gcai jobs get` keeps its own `--wait <seconds>` for a single server-side long-poll. Re-run it until `status` is `succeeded`, `failed`, or `canceled`.

## File processing

Uploads process after they land (text extraction and embeddings). This is not a job envelope: poll the file itself until it is ready.

```bash theme={null}
gcai files upload ./contract.pdf       # returns the file with status: extracting
gcai files get <file_id>               # re-run until status: ready
```