​

Overview

PromptLoop AI’s Batch API v0 allows you to process large datasets, such as CSVs of websites to scrape, using AI tasks. This guide will help you get started with sending inputs, monitoring jobs, and retrieving results.

​

API Authentication

Before using the Batch API, ensure you have an API key. You can obtain this from your PromptLoop dashboard.

​

Creating an API Key

On your PromptLoop dashboard, navigate to the API settings page and create a key. You will only be able to view the key once, so make sure to store it securely. PromptLoop does not store your key.

​

Setting Up Authentication

Include your API key in the x-api-key header of all requests. Here’s an example using cURL:

curl --request GET \
--url https://api.promptloop.com/v0/batches/{id}/results \
--header 'x-api-key: YOUR_API_KEY'

​

Data Format

The Batch API expects input data in JSONL (JSON Lines) format. Each line represents a single input object.

​

Input Structure

Each input object should have: data_uuid: A unique identifier for the input inputs: An array containing the input data. Tasks specify whether the input should be a link or a string. This will be checked in the validation step.

Example:

{"data_uuid": "1", "inputs": ["https://example.com"]}
{"data_uuid": "2", "inputs": ["https://another-example.com"]}

​

Validating Input Data

Ensure your input data is properly formatted and includes all required fields. Invalid data will result in a 400 Bad Request error. You can use the v0/batches/validate-data endpoint to validate your input data before submitting a job.

The response will indicate whether the data is valid or not.

​

API Workflow

Follow these steps to use the Batch API effectively:

POST /v0/batches
Content-Type: application/json

{"data_uuid": "1", "inputs": ["https://example.com"]}
{"data_uuid": "2", "inputs": ["https://another-example.com"]}

GET /v0/batches/{id}

GET /v0/batch/{id}/results

​

API Rate Limits

To ensure fair usage and maintain the performance of our services, we enforce rate limits on our APIs. The rate limits are defined based on the API endpoints and user plans.

​

Default Rate Limits

Each API has a specific rate limit, measured in Transactions Per Minute (TPM). The following table summarizes the default rate limits:

​

Tasks

​

Batches

​

Custom

For custom use-cases requiring higher TPM allocations, please reach out to support. Rate limit increases will be granted on a case-by-case basis for users on Company plans.

​

Handling Rate Limit Errors

If you exceed the rate limit, the API will return a 429 Too Many Requests response. It’s important to implement proper error handling in your application to manage these scenarios effectively.

​

Example Rate Limit Error Handling

Here’s an example of how to handle rate limit errors in your application:

// Example: Handling rate limit errors in a JavaScript application
fetch("https://api.yourdomain.com/[ENDPOINT]")
  .then((response) => {
    if (response.status === 429) {
      console.error(
        "Rate limit exceeded. Please wait before making more requests."
      );
      // Optionally, implement a retry mechanism here
    } else {
      return response.json();
    }
  })
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));

Remember to handle errors and implement retries as necessary throughout this process.

​

Error Handling

The API uses standard HTTP status codes. Common errors:

• 400: Bad Request (e.g., invalid input format)
• 401: Unauthorized (invalid API key)
• 429: Too Many Requests (rate limit exceeded)

Always check the response body for detailed error messages.

​

Batch Size Limits

Batches are limited to 100mb in size per JSONL upload. Your account will also be limited to existing usage limits which can be viewed on your dashboard For larger batches, we recommend retrieving the results using output_type=stream for the /v0/batch/{id}/results endpoint. This allows for more efficient transfers.

​

Webhooks

PromptLoop’s Batch API supports webhooks, allowing you to receive real-time updates about your batch processing jobs.

​

Setting Up a Webhook

When creating a new batch job, you can specify a webhook URL to receive notifications:

POST /v0/batches
Content-Type: application/json
{
"webhook_url": "https://your-webhook-endpoint.com",
"data": [
{"data_uuid": "1", "inputs": ["https://example.com"]},
{"data_uuid": "2", "inputs": ["https://another-example.com"]}
]
}

​

Webhook Payload

When the batch job completes, PromptLoop will send a POST request to your specified webhook URL with the following payload:

{
"status": "completed",
"message": "Your data processing is complete",
"data": "...", // JSON Array of the processed results
"timestamp": "2024-07-23T03:57:20.643Z"
"batch_id": "12345"
}

The data field contains a JSON array with the processed results for each input, similar to the response from the /v0/batch/{id}/results endpoint. The Payload will be sent with a Content-Type: application/json header.

​

Handling Webhook Requests

Ensure your webhook endpoint can:

1. Receive POST requests
2. Process the JSON payload
3. Respond with a 2xx status code to acknowledge receipt

Implement proper security measures, such as verifying the webhook source and using HTTPS.

​

Next Steps

With this overview, you’re ready to explore the specific endpoints. Refer to the API reference for detailed information on each endpoint’s parameters and responses.