Async operations

Some operations take longer to complete and run asynchronously. When you call one of these endpoints, the response returns immediately with a links.self URL and a status field:

{
  "data": {
    "id": "task_abc123",
    "status": "pending"
  },
  "links": {
    "self": "https://app.useomnia.com/api/v1/insights/generation/generation_abc123"
  }
}

There are two ways to know when the task finishes: polling and webhooks.

Polling

Poll the links.self URL until status changes to "completed" (or "failed"). While processing, each polling response includes a Retry-After header telling you how many seconds to wait before the next request:

curl "https://app.useomnia.com/api/v1/insights/generation/generation_abc123" \\
-H "Authorization: Bearer ot_your-token-here"

HTTP/1.1 200 OK
Retry-After: 5

{
  "data": {
    "id": "task_abc123",
    "status": "processing"
  },
  "links": {
    "self": "https://app.useomnia.com/api/v1/insights/generation/generation_abc123"
  }
}

Once the task completes, the full result is included in the response and no Retry-After header is sent:

{
  "data": {
    "id": "task_abc123",
    "status": "completed",
    "results": [ ... ]
  }
}

Respect the Retry-After header. Polling more frequently than the header suggests won't speed things up and will eat into your rate limit budget.

Webhooks

Instead of polling, you can register webhooks to receive a POST request when an async task finishes. This is the recommended approach for production integrations because it removes the need for polling loops and delivers results as soon as they are ready.

You can register and manage webhooks from the API webhooks page.

Supported events

Delivery format

When an event fires, Omnia sends a POST request to your registered URL with a JSON body:

{
  "event": "insight_generated",
  "data": {
    "generationId": "generation_abc123",
    "status": "completed"
  },
  "webhookId": "wh_def456",
  "timestamp": "2026-04-13T14:30:00.000Z"
}

The request includes a Content-Type: application/json header.

Best practices

• Return quickly. Your endpoint should respond with a 2xx status within a few seconds. If you need to do heavy processing, accept the webhook, enqueue the work, and return immediately.
• Be idempotent. In rare cases (network timeouts, retries), you may receive the same event more than once. Use the webhookId and timestamp fields to deduplicate.
• Handle retries gracefully. If your endpoint returns a non-2xx status or times out, Omnia retries delivery up to 2 additional times with exponential backoff. After all retries are exhausted, the delivery is dropped.
• Monitor your endpoint. If deliveries consistently fail, consider logging failures on your side and verifying that your endpoint is reachable.