Skip to Content

Cancel a batch

POSThttps://api.respan.ai/api/v1/batches/{batch_id}/cancel

Cancel an in-progress OpenAI-compatible batch. Already completed requests are not affected.

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

Headers

Parameter Type Required Description and constraints
X-Data-Respan-Params string Optional
Base64-encoded JSON object of Respan request parameters. Legacy X-Data-Keywordsai-Params is still accepted.

Path parameters

Parameter Type Required Description and constraints
batch_id string Required
Batch ID.
Example: "batch_abc123"

Query parameters

Parameter Type Required Description and constraints
provider_id string Required
Provider route with customer-owned credentials, for example openai or parasail.

Request body

The request body is optional.

application/json

Field Type Requirement Description and constraints
$ object Optional body
-

OpenAPI request schema

{
  "type": "object"
}

Responses

200

Batch cancellation initiated.

application/json

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

OpenAPI response schema

{
  "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
}

400

Bad Request

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed
error string Optional
-
detail string Optional
-
error_class string Optional
-
id string Optional
-

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "detail": {
      "type": "string"
    },
    "error_class": {
      "type": "string"
    },
    "id": {
      "type": "string"
    }
  },
  "additionalProperties": true
}
Example
JSON
{ "error": "Invalid request" }

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." }

404

Not Found

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed
error string Optional
-
detail string Optional
-
error_class string Optional
-
id string Optional
-

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "detail": {
      "type": "string"
    },
    "error_class": {
      "type": "string"
    },
    "id": {
      "type": "string"
    }
  },
  "additionalProperties": true
}
Example
JSON
{ "error": "Not found" }

OpenAPI source

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

OpenAPI operation

{
  "summary": "Cancel a batch",
  "operationId": "cancelBatch",
  "tags": [
    "OpenAI Batch"
  ],
  "description": "Cancel an in-progress OpenAI-compatible batch. Already completed requests are not affected.",
  "parameters": [
    {
      "name": "X-Data-Respan-Params",
      "in": "header",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Base64-encoded JSON object of Respan request parameters. Legacy `X-Data-Keywordsai-Params` is still accepted."
    },
    {
      "name": "batch_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Batch ID.",
      "example": "batch_abc123"
    },
    {
      "name": "provider_id",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider route with customer-owned credentials, for example `openai` or `parasail`."
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Batch cancellation initiated.",
      "content": {
        "application/json": {
          "schema": {
            "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
          }
        }
      }
    },
    "400": {
      "description": "Bad Request",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "detail": {
                "type": "string"
              },
              "error_class": {
                "type": "string"
              },
              "id": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "example": {
            "error": "Invalid request"
          }
        }
      }
    },
    "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"
    },
    "404": {
      "description": "Not Found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              },
              "detail": {
                "type": "string"
              },
              "error_class": {
                "type": "string"
              },
              "id": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "example": {
            "error": "Not found"
          }
        }
      }
    }
  },
  "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"
      }
    }
  }
}