Skip to Content

List batches

GEThttps://api.respan.ai/api/v1/batches

List batches from the selected provider using customer-owned credentials. The response is relayed in the provider’s OpenAI-compatible shape.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Query parameters

Parameter Type Required Description and constraints
provider_id string Required
Provider route, for example openai or parasail.
after string Optional
Provider pagination cursor.
limit integer Optional
Maximum batches requested from the provider.
Minimum: 1

Responses

200

OpenAI-compatible batch list.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed
object string Required in parent
Allowed: "list"
data array<object> Required in parent
-
data[] object Array item
Additional properties are allowed
data[].id string Required in parent
Batch ID.
Example: "batch_abc123"
data[].object string Optional
Example: "batch"
data[].endpoint string Optional
Example: "/v1/chat/completions"
data[].input_file_id string Optional
Example: "file-abc123"
data[].output_file_id string or null Optional
Output file ID, available when the batch completes.
data[].error_file_id string or null Optional
Error file ID, when provider errors are available.
data[].completion_window string Optional
Example: "24h"
data[].status string Required in parent
Allowed: "validating", "pending", "in_progress", "finalizing", "completed", "failed", "expired", "cancelling", "cancelled"
Example: "in_progress"
data[].created_at integer Optional
Unix timestamp.
Example: 1710000000
data[].in_progress_at integer or null Optional
-
data[].expires_at integer or null Optional
-
data[].finalizing_at integer or null Optional
-
data[].completed_at integer or null Optional
-
data[].failed_at integer or null Optional
-
data[].expired_at integer or null Optional
-
data[].cancelling_at integer or null Optional
-
data[].cancelled_at integer or null Optional
-
data[].request_counts object Optional
-
data[].request_counts.total integer Optional
Example: 100
data[].request_counts.completed integer Optional
Example: 97
data[].request_counts.failed integer Optional
Example: 3
data[].metadata object Optional
Additional properties are allowed
data[].errors any or null Optional
Provider error details, when available.
first_id string or null Optional
-
last_id string or null Optional
-
has_more boolean Optional
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "object",
    "data"
  ],
  "properties": {
    "object": {
      "type": "string",
      "enum": [
        "list"
      ]
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Batch ID.",
            "example": "batch_abc123"
          },
          "object": {
            "type": "string",
            "example": "batch"
          },
          "endpoint": {
            "type": "string",
            "example": "/v1/chat/completions"
          },
          "input_file_id": {
            "type": "string",
            "example": "file-abc123"
          },
          "output_file_id": {
            "type": "string",
            "nullable": true,
            "description": "Output file ID, available when the batch completes."
          },
          "error_file_id": {
            "type": "string",
            "nullable": true,
            "description": "Error file ID, when provider errors are available."
          },
          "completion_window": {
            "type": "string",
            "example": "24h"
          },
          "status": {
            "type": "string",
            "enum": [
              "validating",
              "pending",
              "in_progress",
              "finalizing",
              "completed",
              "failed",
              "expired",
              "cancelling",
              "cancelled"
            ],
            "example": "in_progress"
          },
          "created_at": {
            "type": "integer",
            "description": "Unix timestamp.",
            "example": 1710000000
          },
          "in_progress_at": {
            "type": "integer",
            "nullable": true
          },
          "expires_at": {
            "type": "integer",
            "nullable": true
          },
          "finalizing_at": {
            "type": "integer",
            "nullable": true
          },
          "completed_at": {
            "type": "integer",
            "nullable": true
          },
          "failed_at": {
            "type": "integer",
            "nullable": true
          },
          "expired_at": {
            "type": "integer",
            "nullable": true
          },
          "cancelling_at": {
            "type": "integer",
            "nullable": true
          },
          "cancelled_at": {
            "type": "integer",
            "nullable": true
          },
          "request_counts": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "example": 100
              },
              "completed": {
                "type": "integer",
                "example": 97
              },
              "failed": {
                "type": "integer",
                "example": 3
              }
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "errors": {
            "nullable": true,
            "description": "Provider error details, when available."
          }
        },
        "additionalProperties": true
      }
    },
    "first_id": {
      "type": "string",
      "nullable": true
    },
    "last_id": {
      "type": "string",
      "nullable": true
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "additionalProperties": true
}

400

provider_id is missing.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "The Files and Batch endpoints require a 'provider_id' field naming the provider to call (e.g. provider_id=openai, provider_id=parasail): a form field on upload, a JSON body field on batch create, a query parameter on every other call. It cannot be inferred: the model names inside a batch file are the provider's own, and follow-up calls carry only opaque IDs." }

401

You haven’t added your own key for the provider in Settings › Providers, or the provider rejected it. Files and batches always run on your own key; Respan credits can’t cover them.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Please add your OpenAI API key in Settings -> Providers. The Files and Batch endpoints always run on your own credentials. Respan credits cannot cover them, because a batch's usage is only known after it completes." }

403

The API key is missing, invalid or expired.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

424

The upstream provider failed.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
-

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Upstream provider request failed." }

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "List batches",
  "operationId": "api_v1_batches_retrieve",
  "tags": [
    "OpenAI Batch"
  ],
  "description": "List batches from the selected provider using customer-owned credentials. The response is relayed in the provider's OpenAI-compatible shape.",
  "parameters": [
    {
      "name": "provider_id",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider route, for example `openai` or `parasail`."
    },
    {
      "name": "after",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Provider pagination cursor."
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1
      },
      "description": "Maximum batches requested from the provider."
    }
  ],
  "responses": {
    "200": {
      "description": "OpenAI-compatible batch list.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "object",
              "data"
            ],
            "properties": {
              "object": {
                "type": "string",
                "enum": [
                  "list"
                ]
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "status"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Batch ID.",
                      "example": "batch_abc123"
                    },
                    "object": {
                      "type": "string",
                      "example": "batch"
                    },
                    "endpoint": {
                      "type": "string",
                      "example": "/v1/chat/completions"
                    },
                    "input_file_id": {
                      "type": "string",
                      "example": "file-abc123"
                    },
                    "output_file_id": {
                      "type": "string",
                      "nullable": true,
                      "description": "Output file ID, available when the batch completes."
                    },
                    "error_file_id": {
                      "type": "string",
                      "nullable": true,
                      "description": "Error file ID, when provider errors are available."
                    },
                    "completion_window": {
                      "type": "string",
                      "example": "24h"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "validating",
                        "pending",
                        "in_progress",
                        "finalizing",
                        "completed",
                        "failed",
                        "expired",
                        "cancelling",
                        "cancelled"
                      ],
                      "example": "in_progress"
                    },
                    "created_at": {
                      "type": "integer",
                      "description": "Unix timestamp.",
                      "example": 1710000000
                    },
                    "in_progress_at": {
                      "type": "integer",
                      "nullable": true
                    },
                    "expires_at": {
                      "type": "integer",
                      "nullable": true
                    },
                    "finalizing_at": {
                      "type": "integer",
                      "nullable": true
                    },
                    "completed_at": {
                      "type": "integer",
                      "nullable": true
                    },
                    "failed_at": {
                      "type": "integer",
                      "nullable": true
                    },
                    "expired_at": {
                      "type": "integer",
                      "nullable": true
                    },
                    "cancelling_at": {
                      "type": "integer",
                      "nullable": true
                    },
                    "cancelled_at": {
                      "type": "integer",
                      "nullable": true
                    },
                    "request_counts": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "example": 100
                        },
                        "completed": {
                          "type": "integer",
                          "example": 97
                        },
                        "failed": {
                          "type": "integer",
                          "example": 3
                        }
                      }
                    },
                    "metadata": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "errors": {
                      "nullable": true,
                      "description": "Provider error details, when available."
                    }
                  },
                  "additionalProperties": true
                }
              },
              "first_id": {
                "type": "string",
                "nullable": true
              },
              "last_id": {
                "type": "string",
                "nullable": true
              },
              "has_more": {
                "type": "boolean"
              }
            },
            "additionalProperties": true
          }
        }
      }
    },
    "400": {
      "description": "`provider_id` is missing.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "The Files and Batch endpoints require a 'provider_id' field naming the provider to call (e.g. provider_id=openai, provider_id=parasail): a form field on upload, a JSON body field on batch create, a query parameter on every other call. It cannot be inferred: the model names inside a batch file are the provider's own, and follow-up calls carry only opaque IDs."
          }
        }
      }
    },
    "401": {
      "description": "You haven't added your own key for the provider in Settings › Providers, or the provider rejected it. Files and batches always run on your own key; Respan credits can't cover them.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Please add your OpenAI API key in Settings -> Providers. The Files and Batch endpoints always run on your own credentials. Respan credits cannot cover them, because a batch's usage is only known after it completes."
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "424": {
      "description": "The upstream provider failed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Upstream provider request failed."
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "securitySchemes": {
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}