Async Requests

This page explains how to use Async mode with the LLM Scraper API, how to retrieve completed responses using the response_url, and how Async works together with callback_url

By default, LLM Scraper requests are processed synchronously.

In synchronous mode, the customer sends a request and waits for the final model response in the same HTTP request.

For longer-running requests, larger prompts, or production workflows where the customer does not want to keep the HTTP connection open, NetNut’s LLM Scraper supports Async mode.

Async mode is recommended for workflows that require better stability, longer processing time, backend automation, or request tracking.

Async mode is supported with all LLM Models

---

Parameter: async

Field	Value
Type	Boolean
Default	false
Description	When set to true, the request is processed asynchronously and the API returns a response_url instead of waiting for the final model response.

---

How Async Works

When async=true, the request flow changes from a direct response flow to a two-step flow.

Step 1: Send the Async Request

The customer sends a regular LLM Scraper request with async=true.

{  
  "engine": "perplexity",
  "prompt": "What are the latest trends in the coffee industry?",
  "async": true
}

Step 2: Receive the Initial Response

The API immediately returns a confirmation response.

{  
    "message": "request received",
    "traceId": "123e4567-e89b-12d3-a456-426614174000",
    "response_url": "https://llm-scraper.netnut.io/search/response/123e4567-e89b-12d3-a456-426614174000"
}

Step 3: Retrieve the Final Response

The customer sends a GET request to the returned response_url.

GET https://llm-scraper.netnut.io/search/response/123e4567-e89b-12d3-a456-426614174000

Each response is protected with Basic Auth. Include valid Basic Auth credentials when retrieving it.

Once the request is completed, the API returns the final LLM Scraper response.

---

Response URL Behavior

The response_url is used to retrieve the completed async response.

If the request is still processing, the API returns:

{  
  "status": "processing",
  "message": "Request is still processing",
  "traceId": "123e4567-e89b-12d3-a456-426614174000"
}

The customer should retry the same response_url until the final response is available.

Completed async responses are available through the response_url for 2 hours after the request is completed.

---

Response Storage

Completed async responses are stored on NetNut internal servers for up to 2 hours after the request is completed.

During this period, customers can retrieve the final response using the provided response_url.

After the storage period expires, the response_url may no longer return the completed response.

---

Async with callback_url

Async mode can also be used together with callback_url.

When both async=true and callback_url are provided, the API still returns the initial async response with the response_url.

Once processing is completed, NetNut sends a notification to the customer’s callback_url.

In this flow, the callback does not include the full final response. Instead, it notifies the customer that the request is complete and includes the response_url.

Example Request

{  
   "model": "perplexity",
   "prompt": "What are the latest trends in the coffee industry?",  
   "async": true,  
   "callback_url": "https://customer-api.com/llm-callback"
}

Example Callback Payload

{
  "traceId": "123e4567-e89b-12d3-a456-426614174000",
  "status_code": 200,
  "response_url": "https://llm-scraper.netnut.io/search/response/123e4567-e89b-12d3-a456-426614174000"
}

The customer can then use the response_url to retrieve the completed result.

---

Async vs Callback URL

Mode	Final Response Flow
Sync	Final response is returned in the same request
Async	Customer retrieves the final response from response_url
Callback URL	Final response is sent directly to the customer’s callback_url
Async + Callback URL	Callback sends a completion notification with response_url; customer retrieves the final response from it