How to Use Laravel Pipeline for Long-Running API Integrations (with Guzzle Example)

Learn how Laravel Pipeline helps manage long third-party API calls using Guzzle HTTP with cleaner, modular, and efficient request handling.

Mastering Laravel Pipeline for Long-Running API Calls

Q: Can I use async requests inside a Laravel pipeline?

Yes. Guzzle’s postAsync() works great for non-blocking API calls inside a pipeline.

Q: How do I handle timeouts or failures in Guzzle?

Use try/catch with proper timeout and connect_timeout settings, or add retry middleware for resilience.

Long third-party API responses can bring your Laravel app to a crawl — but not if you harness the power of the Laravel Pipeline.
In this article, we’ll learn how to streamline long API requests using Guzzle HTTP and Laravel’s Pipeline pattern, ensuring your code stays clean, testable, and resilient.

What is the Laravel Pipeline?

A pipeline in Laravel is a design pattern that allows you to pass data through a series of steps (known as “pipes”) before reaching the final destination.
Think of it like a factory assembly line — each step processes the data a little more.

In Laravel, the Illuminate\Pipeline\Pipeline class lets you chain operations like this:

app(Pipeline::class)

->send($data)

->through([

PipeOne::class,

PipeTwo::class,

PipeThree::class,

])

->thenReturn();

This pattern is widely used in Laravel’s middleware, request validation, and even job processing — making it a perfect fit for complex request flows such as slow third-party API calls.

The Problem – Long Waiting Third-Party API

Imagine you’re building a Laravel app that fetches real-time currency conversion or vehicle insurance quotes from an external API.
Some of these APIs may take 5–10 seconds or even longer to respond.

Directly calling such APIs in controllers leads to:

Poor user experience (waiting for a response)
Timeout errors or failed requests
Messy code with multiple try/catch blocks

By using a Pipeline, we can:
✅ Structure the process into smaller, testable units
✅ Add or remove logic dynamically
✅ Integrate retries and error handling elegantly

Setting up the Example

For this demo, let’s simulate a long-running third-party API that returns user profile data.

We’ll use:

Laravel 11+
Guzzle HTTP Client
Pipeline pattern

Install Guzzle:

Our goal:
Make a clean pipeline that:

Validates request data
Prepares API payload
Calls the third-party API
Handles long wait & errors gracefully
Returns structured response

Step-by-Step Implementation

1. Create the Pipeline Directory

Inside app/ , create:

app/
├── Pipelines/
│ ├── ValidateRequest.php
│ ├── PrepareRequest.php
│ ├── CallApi.php
│ ├── HandleResponse.php
│ └── HandleError.php

2. Define Each Pipe

ValidateRequest.php

namespace App\Pipelines;

use Closure;
use Illuminate\Validation\ValidationException;
use Illuminate\Support\Facades\Validator;

class ValidateRequest
{
    public function handle($request, Closure $next)
    {
        $validator = Validator::make($request, [
            'user_id' => 'required|numeric',
        ]);

        if ($validator->fails()) {
            throw new ValidationException($validator);
        }

        return $next($request);
    }
}

PrepareRequest.php

namespace App\Pipelines;

use Closure;

class PrepareRequest
{
    public function handle($request, Closure $next)
    {
        $request['timestamp'] = now()->toISOString();
        return $next($request);
    }
}

CallApi.php

Here we simulate a slow API using Guzzle with timeout and retry.

namespace App\Pipelines;

use Closure;
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

class CallApi
{
    public function handle($request, Closure $next)
    {
        $client = new Client([
            'timeout' => 15.0,
            'connect_timeout' => 5.0,
        ]);

        try {
            $response = $client->post('https://thirdparty.example.com/api/data', [
                'json' => $request
            ]);

            $request['api_response'] = json_decode($response->getBody(), true);
        } catch (RequestException $e) {
            $request['api_error'] = $e->getMessage();
        }

        return $next($request);
    }
}

HandleResponse.php

namespace App\Pipelines;

use Closure;

class HandleResponse
{
    public function handle($request, Closure $next)
    {
        if (!empty($request['api_response'])) {
            $request['final_output'] = [
                'status' => 'success',
                'data' => $request['api_response']
            ];
        }

        return $next($request);
    }
}

HandleError.php

namespace App\Pipelines;

use Closure;

class HandleError
{
    public function handle($request, Closure $next)
    {
        if (!empty($request['api_error'])) {
            return [
                'status' => 'failed',
                'error' => $request['api_error'],
            ];
        }

        return $next($request);
    }
}

3. Execute the Pipeline in Controller

use Illuminate\Pipeline\Pipeline;
use App\Pipelines\{
    ValidateRequest,
    PrepareRequest,
    CallApi,
    HandleResponse,
    HandleError
};

class ApiController extends Controller
{
    public function process(Request $request)
    {
        $data = $request->all();

        $result = app(Pipeline::class)
            ->send($data)
            ->through([
                ValidateRequest::class,
                PrepareRequest::class,
                CallApi::class,
                HandleError::class,
                HandleResponse::class,
            ])
            ->thenReturn();

        return response()->json($result);
    }
}

Complete Example Flow

Let’s test it by calling the route:

Route::post('/process-api', [ApiController::class, 'process']);

Input:

{ "user_id": 123 }

Output (success):

{
  "status": "success",
  "data": {
    "name": "John Doe",
    "email": "john@example.com"
  } }

Output (error):

{
  "status": "failed",
  "error": "cURL error 28: Operation timed out" 
}

The pipeline ensures:

Each stage is modular.
Errors are caught at the right place.
You can add or remove any pipe easily.

Advanced Optimization Tips

Use Laravel Queues
Offload slow API calls to background jobs:
```
php artisan queue:work
```
Guzzle Retry Middleware
Implement retry strategy:
```
'retry' => 3,
'delay' => 1000,
```
Timeout & Fallback Handling
Always set reasonable timeouts (10–15s).
Logging Slow Requests
Monitor with Laravel Telescope or Sentry.
Async Calls with Guzzle
Use $client->postAsync() for parallel execution.

Conclusion

Laravel Pipelines make complex operations like long third-party API requests manageable, modular, and clean.
By splitting logic into pipes, you gain flexibility, scalability, and improved error handling — all while keeping your code elegant and maintainable.

When combined with queues, caching, and retries, pipelines can handle even the slowest API integrations gracefully.

External Sources

FAQs

1. What is the Laravel Pipeline used for?
It’s a design pattern to process data through multiple stages. Perfect for handling transformations, API requests, or sequential tasks.

2. Can I use async requests inside a Laravel pipeline?
Yes. Guzzle’s postAsync() works great for non-blocking API calls inside a pipeline.

3. How do I handle timeouts or failures in Guzzle?
Use try/catch with proper timeout and connect_timeout settings, or add retry middleware for resilience.

4. Should I use pipelines for all API calls?
Not necessarily. Pipelines shine in multi-step, conditional processes — simple API calls can stay inline.

5. Can I queue a pipeline in Laravel?
Absolutely. Wrap your pipeline inside a Job class for asynchronous execution.

5 min read

Nov 19, 2025

By Chandan Mishra

Your email address will not be published. Required fields are marked *