---
title: "Create async rerank"
method: POST
path: "/v1/async/rerank"
tags: ["Async Jobs"]
---

# Create async rerank

`POST /v1/async/rerank`

Submits a rerank request for asynchronous execution. Returns a job ID immediately
with HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result.

## Headers

- `x-bf-async-job-result-ttl` integer
- `x-bf-async-webhook` string

## Request body

- RerankRequest
  - `model` string, required — Model in provider/model format
  - `query` string, required — Query used to score and reorder documents
  - `documents` RerankDocument[], required — Documents to rerank
    - `text` string, required — Document text content
    - `id` string — Optional document identifier
    - `meta` object — Optional document metadata
  - `fallbacks` string[] — Fallback models in provider/model format
  - `top_n` integer — Maximum number of ranked results to return
  - `max_tokens_per_doc` integer — Maximum tokens to consider per document (provider-dependent)
  - `priority` integer — Request priority hint (provider-dependent)
  - `return_documents` boolean — Whether to include document content in each result

## Response `202`

Job accepted for processing

- AsyncJobResponse — Response returned when creating or polling an async job
  - `id` string, required — Unique identifier for the async job
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required — The status of an async job
  - `expires_at` string, date-time — When the job result expires and will be cleaned up
  - `created_at` string, date-time, required — When the job was created
  - `completed_at` string, date-time — When the job completed (successfully or with failure)
  - `status_code` integer — HTTP status code of the completed operation
  - `result` unknown
  - `error` BifrostError — Error response from Bifrost
    - `event_id` string
    - `type` string
    - `is_bifrost_error` boolean
    - `status_code` integer
    - `error` ErrorField
      - `type` string
      - `code` string
      - `message` string
      - `param` string
      - `event_id` string
    - `extra_fields` BifrostErrorExtraFields
      - `provider` 'openai' | 'azure' | 'anthropic' | 'bedrock' | 'cohere' | 'vertex' | 'vllm' | 'mistral' | 'ollama' | 'groq' | 'sgl' | 'parasail' | 'perplexity' | 'replicate' | 'cerebras' | 'deepseek' | 'gemini' | 'openrouter' | 'elevenlabs' | 'huggingface' | 'nebius' | 'xai' | 'runway' | 'fireworks' — AI model provider identifier
      - `model_requested` string
      - `request_type` string

## Other responses

- `400` — Bad request
- `500` — Internal server error

---

[API](https://skmtc.net/getbifrost/apis/bifrost-api.md) · [All operations](https://skmtc.net/getbifrost/apis/bifrost-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbifrost/bifrost-api/versions/f8cab88f64ea/schema)