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

# Best Practices

> Recommended settings and patterns for polling Cobalt operations.

## Polling Interval

A poll interval of **1 second** works well for most operations. Cobalt typically processes operations within a few seconds to a couple of minutes depending on the EHR system.

If you want to reduce API calls, you can increase the interval to 2-3 seconds with minimal impact on perceived latency.

## Timeout

Set a timeout based on the operation type:

| Operation    | Recommended Timeout |
| ------------ | ------------------- |
| Appointments | 2 minutes           |
| Patients     | 2 minutes           |
| Notes        | 3 minutes           |
| Documents    | 3 minutes           |
| Insurance    | 2 minutes           |

Processing times vary by EHR system. If you experience frequent timeouts, increase the timeout rather than reducing the poll interval.

## Handle Timeouts Gracefully

A timeout does not mean the operation failed. It means the result wasn't available within your wait window. The operation may still complete successfully in the background.

If a timeout occurs:

1. **Log the `job_id`** so you can look it up later.
2. **Check back later** by calling `GET /v1/webhook-events?job_id={job_id}` at any point in the future.
3. **Don't retry the original operation** unless you've confirmed it failed. Creating a duplicate appointment or patient is worse than waiting a bit longer.

```jsx theme={null}
try {
    const result = await awaitResult(jobId, { timeoutMs: 120000 });
    // Handle success or failure
} catch (error) {
    if (error.message.includes('Timed out')) {
        // The operation may still succeed - don't retry blindly
        console.log(`Operation still processing. Track with job_id: ${jobId}`);
    }
}
```

## When to Use Webhooks Instead

Polling works well for low-volume, on-demand operations. For high-volume or background processing, [webhooks](/docs/webhooks/overview) are more efficient:

* **Use polling** when a user is waiting for an immediate result (e.g., a "Schedule Appointment" button in your UI).
* **Use webhooks** when processing records in bulk or when operations happen in the background without a user waiting.
* **Use both** for the best of both worlds: webhooks for production event processing, polling for ad-hoc operations and debugging.

<Note>
  You do not need to register a webhook URL to use the polling approach. Cobalt tracks all operation results internally regardless of whether you have webhooks configured.
</Note>

## Supported Operations

Any Cobalt API operation that returns a `job_id` in its response supports this polling pattern. This includes:

* **Appointments** - Create and update
* **Patients** - Create
* **Notes** - Create
* **Documents** - Upload
* **Tasks** - Create
* **Messages** - Create
* **Insurance** - Add to patient
* **Referring Providers** - Create
* **Telephone Encounters** - Create