> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List bulk transfers

# List Bulk Transfers

Retrieve a paginated list of bulk transfers with support for filtering, sorting, and status tracking. This endpoint returns all bulk transfers associated with your account in chronological order.

## Endpoint

```bash theme={null}
GET /bulk-transfers
```

## Query Parameters

**status** `string`

Filter transfers by their current status:

* `created` - Initialized but not executed
* `executing` - Currently processing
* `cancelled` - Manually cancelled
* `expired` - Past execution window
* `completed` - All transfers processed

**after** `string`

Cursor for fetching next page of results

* Use value from `pagination.after` in previous response

**before** `string`

Cursor for fetching previous page of results

* Use value from `pagination.before` in previous response

**limit** `integer` (default: 10)

Number of records to return per page

* Minimum: 1
* Maximum: 100
* Default: 10

## Response Format

**data** `array`

Array of bulk transfer objects

**Bulk Transfer Object**

**id** `string`

Unique identifier for the bulk transfer

**description** `string`

Optional description of the bulk transfer

**reference** `string`

Your unique reference for the bulk transfer

**status** `string`

Current status of the bulk transfer

**total\_transfer\_count** `integer`

Total number of transfers in the batch

**successful\_transfer\_count** `integer`

Number of successfully completed transfers

**failed\_transfer\_count** `integer`

Number of failed transfers

**expires\_at** `string`

ISO-8601 timestamp when the bulk transfer expires

**created\_at** `string`

ISO-8601 timestamp of creation

**updated\_at** `string`

ISO-8601 timestamp of last update

**metadata** `object`

Additional metadata about the transfer

**pagination** `object`

**before** `string`

Cursor for the previous page

**after** `string`

Cursor for the next page

**limit** `integer`

Number of records per page

## Example Request

```bash cURL theme={null}
curl -X GET "https://payout-staging.spendjuice.com/v1/bulk-transfers?limit=10" \
-H "Authorization:  YOUR_API_KEY"
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://payout-staging.spendjuice.com/v1/bulk-transfers?limit=10',
  {
    headers: {
      'Authorization': ' YOUR_API_KEY'
    }
  }
);
```

```python Python theme={null}
import requests

response = requests.get(
    'https://payout-staging.spendjuice.com/v1/bulk-transfers',
    params={'limit': 10},
    headers={'Authorization': ' YOUR_API_KEY'}
)
```

## Response Examples

```json 200 Success theme={null}
{
  "data": [
    {
      "created_at": "2024-10-02T17:39:26.049258",
      "description": "October Vendor Payments",
      "expires_at": "2024-10-03T17:39:25Z",
      "failed_transfer_count": 0,
      "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
      "items": [],
      "metadata": {},
      "owner": {
        "id": "65fb1bf9-10e7-4556-8005-0c3249b8df36",
        "type": "personal"
      },
      "reference": "oct_2024_vendors",
      "status": "created",
      "successful_transfer_count": 0,
      "total_transfer_count": 0,
      "updated_at": "2024-10-02T17:39:26Z"
    }
  ],
  "pagination": {
    "after": "b101f718-d133-450c-a572-c281c7341803",
    "before": null,
    "limit": 10
  }
}
```

```json 400 Invalid Parameters theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid query parameters",
    "details": {
      "limit": ["Must be between 1 and 100"]
    }
  }
}
```

## Error Handling

> **400 - Invalid Request**
>
> Occurs when:
>
> * Invalid status value provided
> * Limit outside allowed range
> * Invalid cursor format

> **401 - Unauthorized**
>
> Occurs when:
>
> * Missing API key
> * Invalid API key
> * Expired API key

> **403 - Forbidden**
>
> Occurs when:
>
> * Insufficient permissions
> * Account restrictions

## Pagination

The API uses cursor-based pagination for reliable list operations:

1. Initial request: Specify desired `limit`
2. Subsequent requests: Use the `after` cursor from previous response
3. Previous page: Use the `before` cursor if available

> [!NOTE]
>
> For optimal performance:
>
> * Use reasonable page sizes (10-50 records)
> * Cache results when appropriate
> * Implement progressive loading in your UI

## Rate Limits

> [!NOTE]
>
> This endpoint has the following rate limits:
>
> * 100 requests per minute per API key
> * Maximum of 1000 requests per hour
> * Burst limit: 20 requests per second

## Best Practices

1. **Efficient Filtering**
   * Use status filters to reduce response size
   * Combine filters for precise results
   * Cache frequently accessed data

2. **Pagination Handling**
   * Store cursors temporarily for navigation
   * Implement infinite scroll for large lists
   * Show loading states during fetches

3. **Error Handling**
   * Implement proper retry logic
   * Handle rate limits gracefully
   * Log pagination errors

4. **Performance**
   * Use appropriate page sizes
   * Cache responses when possible
   * Monitor API response times

> **Need Help?**
>
> For additional assistance:
>
> * Check our [Error Handling Guide](https://docs.juicyway.com/errors.md)
> * Review [Pagination Best Practices](https://docs.juicyway.com/api-overview/pagination)
> * Contact [Support](mailto:support@juicyway.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.