---
title: prefactor_http.endpoints.bulk module
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

# prefactor_http.endpoints.bulk module

Bulk endpoint client for the Prefactor API.

### *class* prefactor_http.endpoints.bulk.BulkClient(http_client: [PrefactorHttpClient](prefactor_http.md#prefactor_http.PrefactorHttpClient))

Bases: `object`

Client for bulk action operations.

Execute multiple POST actions in a single HTTP request.
This endpoint allows you to batch multiple operations together, reducing
the number of round trips to the API.

Key Features:
: - Each item in the request is processed independently in its own
    database transaction
  - Processing stops early if any item returns an error
  - All successfully processed items up to the error are returned
  - Any unprocessed items (after the first error) are excluded from the result
  - All items must include a unique idempotency_key (minimum 8 characters)
  - Results are returned as a map keyed by idempotency_key

### Example

```
``
```

```
`
```

python
request = BulkRequest(

> items=[
> : BulkItem(  # type: ignore[call-arg]
>   : \_type=”agent_instances/register”,
>     idempotency_key=”register-instance-001”,
>     agent_id=”agent_123”,
>     agent_version={“name”: “My Agent”, “external_identifier”: “v1.0.0”},
>     agent_schema_version={
>     <br/>
>     > “external_identifier”: “v1.0.0”,
>     > “span_type_schemas”: [
>     <br/>
>     > > {
>     > > : “name”: “agent:llm”,
>     > >   “title”: “LLM Call”,
>     > >   “params_schema”: {
>     > >   <br/>
>     > >   > “type”: “object”,
>     > >   > “properties”: {
>     > >   <br/>
>     > >   > > “model”: {“type”: “string”},
>     > >   > > “prompt”: {“type”: “string”},
>     > >   <br/>
>     > >   > },
>     > >   > “required”: [“model”, “prompt”],
>     > >   <br/>
>     > >   },
>     > >   “result_schema”: {
>     > >   <br/>
>     > >   > “type”: “object”,
>     > >   > “properties”: {
>     > >   <br/>
>     > >   > > “response”: {“type”: “string”},
>     > >   <br/>
>     > >   > },
>     > >   <br/>
>     > >   },
>     <br/>
>     > > },
>     <br/>
>     > ],
>     <br/>
>     },
>   <br/>
>   ),
>   BulkItem(  # type: ignore[call-arg]
>   <br/>
>   > \_type=”agent_spans/create”,
>   > idempotency_key=”create-span-001”,
>   > agent_instance_id=”instance_123”,
>   > schema_name=”agent:llm”,
>   > status=”active”,
>   <br/>
>   ),

> ]

)
response = await client.bulk.execute(request)
print(response.outputs[“create-span-001”].status)

```
``
```

```
`
```

#### *async* execute(request: [BulkRequest](prefactor_http.models.bulk.md#prefactor_http.models.bulk.BulkRequest)) → [BulkResponse](prefactor_http.models.bulk.md#prefactor_http.models.bulk.BulkResponse)

Execute multiple queries/actions in a single request.

* **Parameters:**
  **request** – The bulk request containing items to process.
* **Returns:**
  BulkResponse with outputs keyed by idempotency_key.
* **Raises:**
  * [**PrefactorValidationError**](prefactor_http.md#prefactor_http.PrefactorValidationError) – If the request is invalid.
  * [**PrefactorRetryExhaustedError**](prefactor_http.md#prefactor_http.PrefactorRetryExhaustedError) – If the request fails after all retries.
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – If the API returns an error response.