# API Overview
Source: https://docs.promptloop.com/get-started/api-overview

Run AI tasks on large datasets with PromptLoop

## 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](https://promptloop.com/account/settings) 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:

```json theme={null}
{"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.

<Accordion title="Examples of Validation Errors">
  **Too many inputs:**

  ```json theme={null}
  {
  		"status": "success",
  		"data": {
  				"job_count": 4,
  				"job_improper_format_count": 1,
  				"job_improper_format": [
  						{
  								"error_index": 4,
  								"error_message": "JSONL object inputs length does not match task inputs length: 1 vs 2. Expecting inputs schema: [{\"name\":\"websiteUrl\",\"schema\":\"LinkItemSchema\",\"description\":\"Website URL\"}]"
  						}
  				]
  		},
  		"message": "",
  		"error": null
  }
  ```

  **Incorrect Input Type:**

  ```json theme={null}
  {
  		"status": "success",
  		"data": {
  				"job_count": 4,
  				"job_improper_format_count": 1,
  				"job_improper_format": [
  						{
  								"error_index": 4,
  								"error_message": "JSONL object inputs do not match task inputs: Expected a valid URL for input: websiteUrl, received: Not a Link"
  						}
  				]
  		},
  		"message": "",
  		"error": null
  }
  ```
</Accordion>

## API Workflow

Follow these steps to use the Batch API effectively:

<Steps>
  <Step title="Launch a Job">
    Send your JSONL data to the `/v0/launch-job` endpoint to start processing.
    Ensure your data is properly formatted and includes the required fields.

    ```http theme={null}
    POST /v0/batches
    Content-Type: application/json

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

    You'll receive a job ID in response, which you'll use in the next steps.
  </Step>

  <Step title="Monitor Job Status">
    Check the progress of your job using the `/v0/job-status/{id}` endpoint.
    Replace `{id}` with the job ID you received in step 1.

    ```http theme={null}
    GET /v0/batches/{id}
    ```

    The response will include the current status of your job (e.g., "in\_progress", "completed", "failed").
  </Step>

  <Step title="Retrieve Results">
    Once the job status is "completed", fetch the processed data using the `/v0/batch/{id}/results` endpoint.

    ```http theme={null}
    GET /v0/batch/{id}/results
    ```

    The response will contain the results of your batch processing job.
    The results will be returned in json format, with results presented in key-value pairs within the object. One object for each input row.
    Each object will also include the `data_uuid` passed in with that row. Order is not guaranteed to be maintained when processing, so use this to identify rows.
  </Step>
</Steps>

## 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

| API Method | Endpoint         | TPM Restriction |
| ---------- | ---------------- | --------------- |
| `GET`      | `/v0/tasks`      | 20 TPM          |
| `GET`      | `/v0/tasks/{id}` | 10 TPM          |
| `POST`     | `/v0/tasks/{id}` | 5 TPM           |

#### Batches

| API Method | Endpoint                    | TPM Restriction |
| ---------- | --------------------------- | --------------- |
| `GET`      | `/v0/batches`               | 10 TPM          |
| `POST`     | `/v0/batches`               | 4 TPM           |
| `POST`     | `/v0/batches/validate-data` | 20 TPM          |
| `GET`      | `/v0/batches/{id}`          | 20 TPM          |
| `PUT`      | `/v0/batches/{id}`          | 4 TPM           |
| `GET`      | `/v0/batches/{id}/results`  | 10 TPM          |

### 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:

```javascript theme={null}
// 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](https://www.promptloop.com/account/settings/usage)
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](/v0) for detailed information on each endpoint's parameters and responses.


# CLI Quickstart
Source: https://docs.promptloop.com/get-started/cli-quickstart

Install, authenticate, and run your first PromptLoop command in minutes

## Install the CLI

```bash theme={null}
npm install -g @promptloop/cli
```

Or run without a global install:

```bash theme={null}
npx @promptloop/cli --help
```

## Authenticate

Use browser login (recommended):

```bash theme={null}
promptloop auth login --browser
```

Or authenticate directly with an API key:

```bash theme={null}
promptloop auth login --api-key YOUR_API_KEY
```

Verify auth status:

```bash theme={null}
promptloop auth whoami
```

<Note>
  Create API keys from your PromptLoop settings page:
  [promptloop.com/account/settings](https://promptloop.com/account/settings)
</Note>

## Run your first task

<img alt="PromptLoop CLI flow diagram" />

List tasks:

```bash theme={null}
promptloop tasks list
```

Run one task with inputs:

```bash theme={null}
promptloop tasks run YOUR_TASK_ID --inputs "https://promptloop.com"
```

## Run a batch job

Create a batch from a CSV or JSON file:

```bash theme={null}
promptloop batches create --task-id YOUR_TASK_ID --file ./input.csv
```

Watch status:

```bash theme={null}
promptloop batches status YOUR_BATCH_ID --watch
```

Fetch results:

```bash theme={null}
promptloop batches results YOUR_BATCH_ID --wait
```

## Claude quick copy

Use this as a drop-in prompt for Claude when you want it to run the same CLI workflow.

<CodeGroup>
  ```md Prompt template theme={null}
  You are helping me run PromptLoop from the CLI.

  1. Confirm I am authenticated:
     - promptloop auth whoami
  2. List available tasks:
     - promptloop tasks list
  3. Run a task:
     - promptloop tasks run YOUR_TASK_ID --inputs "https://promptloop.com"
  4. Run a batch from file:
     - promptloop batches create --task-id YOUR_TASK_ID --file ./input.csv
  5. Check progress:
     - promptloop batches status YOUR_BATCH_ID --watch
  6. Fetch results:
     - promptloop batches results YOUR_BATCH_ID --wait

  Ask me for missing IDs before executing commands.
  ```

  ```bash Command sequence theme={null}
  promptloop auth whoami
  promptloop tasks list
  promptloop tasks run YOUR_TASK_ID --inputs "https://promptloop.com"
  promptloop batches create --task-id YOUR_TASK_ID --file ./input.csv
  promptloop batches status YOUR_BATCH_ID --watch
  promptloop batches results YOUR_BATCH_ID --wait
  ```
</CodeGroup>


# Introduction
Source: https://docs.promptloop.com/get-started/introduction

Empower your team with AI-driven data tasks and business intelligence

## Core Concepts

PromptLoop empowers your team with cutting-edge AI tools to automate and enhance your data tasks. Create tasks that accomplish your work, including research, web scraping, text analysis, and building valuable company datasets.
Our API allows you to run AI tasks and integrate this data into your application.

<CardGroup>
  <Card title="Tasks" icon="list-check" href="https://promptloop.com/account/custom">
    Create actions for our systems to accomplish, with inputs and outputs
  </Card>

  <Card title="Datasets" icon="database" href="https://promptloop.com/account/datasets">
    Manage and process large amounts of data with AI-powered tasks. API results
    are also saved here.
  </Card>

  <Card title="Credits and Packages" icon="plug" href="https://promptloop.com/demo">
    Learn more about our plans and API packages for companies
  </Card>

  <Card title="Get Started" icon="play" href="#steps-to-get-started">
    Learn how to create and run your first task
  </Card>
</CardGroup>

## Steps to Get Started

Before diving into the API, follow these steps to set up and familiarize yourself with the PromptLoop platform:

<Steps>
  <Step title="Define your goal and create a task">
    Start by clearly defining the objective you want to achieve with AI processing. Then, use PromptLoop's task creation interface to set up a task that aligns with your goal. This could involve selecting from pre-built templates or creating a custom task using our editor.
    You can create a task in your [dashboard](https://www.promptloop.com/account/custom).
  </Step>

  <Step title="Test and edit your task">
    Once your task is created, use the testing interface to run it on sample data.
    This allows you to verify that the task produces the desired output. If
    needed, refine your task by adjusting parameters, prompts, or logic to improve
    accuracy and relevance of results.
  </Step>

  <Step title="Run a dataset on your task">
    After you're satisfied with your task's performance on test data, prepare your
    full dataset for processing. Use the PromptLoop interface to upload your
    dataset and initiate the processing job. This step is where you'll transition
    to using the Batch API for larger scale operations.
  </Step>

  <Step title="Review, filter, search, and export results">
    Once processing is complete, examine the results using PromptLoop's built-in tools. You can filter and search through the output to find specific information. Finally, export the processed data in your preferred format for further use or analysis in other systems.
  </Step>
</Steps>

After completing these steps, you'll be well-prepared to \`leverage the full power of the Batch API for your large-scale data processing needs.

For a detailed guide on each step, visit our [Getting Started](/get-started/quickstart) page.

<Card title="Book a Demo" icon="calendar" href="https://promptloop.com/demo">
  Learn more about how PromptLoop can support your specific business needs
</Card>


# MCP Quickstart
Source: https://docs.promptloop.com/get-started/mcp-quickstart

Connect PromptLoop to Cursor, Claude, ChatGPT, or Codex with one-click OAuth — no API keys to paste

PromptLoop ships a remote [Model Context Protocol](https://modelcontextprotocol.io) server so any
MCP-capable AI client can run your research tasks, launch batches, search for companies, and check
usage — all authenticated with OAuth. There is nothing to self-host.

## Server URL

```
https://promptloop.com/mcp
```

The transport is **Streamable HTTP** and auth is **OAuth 2.1** (PKCE + Dynamic Client Registration).
The first time a client connects it opens a browser window where you sign in and approve access. The
connection is scoped to your team and can be revoked anytime from
[API settings](https://promptloop.com/account/settings).

<Note>
  The fastest way to connect is the in-app installer:
  [promptloop.com/mcp/install](https://promptloop.com/mcp/install) has one-click buttons and
  copy-paste configuration for every client.
</Note>

## Connect your client

<Tabs>
  <Tab title="Cursor">
    Add this to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "promptloop": {
          "url": "https://promptloop.com/mcp"
        }
      }
    }
    ```

    Cursor shows a **Needs login** prompt — click it to authorize with OAuth.
  </Tab>

  <Tab title="Claude">
    In Claude (web or desktop): **Settings → Connectors → Add custom connector**, set the URL to
    `https://promptloop.com/mcp`, then click **Connect** and sign in.

    Custom connectors require a paid Claude plan (Pro, Max, Team, or Enterprise).
  </Tab>

  <Tab title="ChatGPT">
    Enable **Settings → Connectors → Advanced settings → Developer mode**. In the Connectors tab
    click **Create**, set the MCP server URL to `https://promptloop.com/mcp`, set Authentication to
    **OAuth**, then create and authorize.
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add promptloop --url https://promptloop.com/mcp
    ```

    Restart Codex — a browser window opens for OAuth on the first tool call.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http promptloop https://promptloop.com/mcp
    ```

    Run `/mcp` inside Claude Code and pick `promptloop` to authenticate.
  </Tab>
</Tabs>

## Available tools

| Tool                                                             | What it does                                       |
| ---------------------------------------------------------------- | -------------------------------------------------- |
| `list_tasks`, `get_task`                                         | Discover saved tasks and their inputs/outputs      |
| `run_task`                                                       | Run a saved task on one or more inputs             |
| `run_dynamic_research`                                           | Ad-hoc research on a single website, no saved task |
| `create_task`, `edit_task`, `test_task`                          | Build and refine tasks from natural language       |
| `create_batch`, `list_batches`, `get_batch`, `get_batch_results` | Run and track large async jobs                     |
| `cancel_batch`, `retry_batch`, `set_batch_webhook`               | Manage batches                                     |
| `search_companies`                                               | Find companies matching an ICP and export a CSV    |
| `get_usage`, `get_limits`                                        | Check credit usage and plan limits                 |

## Setup prompt

Paste this into your assistant so it knows how to drive PromptLoop:

```md Prompt template theme={null}
You have access to the PromptLoop MCP server (https://promptloop.com/mcp).

- Use list_tasks to find saved research tasks before creating a new one.
- Use run_task for a saved task, or run_dynamic_research for a one-off website.
- Use create_task / test_task to build and validate a new task.
- Use create_batch for large lists, then get_batch and get_batch_results.
- Use search_companies to build a target list, and get_usage / get_limits to check credits.

Confirm with me before launching large batch jobs.
```

## Revoking access

Every connection is backed by a short-lived, auto-rotating team API key. To disconnect a client,
revoke its key from [API settings](https://promptloop.com/account/settings) — the client will stop
working immediately.


# Quickstart
Source: https://docs.promptloop.com/get-started/quickstart

Start using PromptLoop to automate and enhance your data tasks in minutes

## Welcome to the PromptLoop API

This API provides access to [PromptLoop](https://promptloop.com) functionality.

PromptLoop is an AI platform that lets you:

* Enrich company datasets with AI web research
* Build proprietary Go-To-Market datasets for Sales & Marketing
* Automate repeatable AI transformations on spreadsheet text data
* Scrape and extract structured data from websites and lists

## Account Set up

To use the API, you will need access to a PromptLoop account. You can sign up for a free trial and if you are interested
in building with the api you can reach out to [team@promptloop.com](mailto:team@promptloop.com).

* Create an account on [PromptLoop.com](https://promptloop.com)
* Follow the guides to create an AI agent to run [(A PromptLoop Task)](https://www.promptloop.com/docs/getting-started)
* Create an API key at [settings page](https://promptloop.com/account/settings)

<Note>
  The API lets you run existing PromptLoop Tasks so you will need to set them up
  there before running the API
</Note>

## Run a single Job

Once you have a task and a task ID, you can provide an input and get back live data just like you would on the PromptLoop Platform.

**Request**

```bash Request theme={null}
curl --request POST \
  --url https://api.promptloop.com/v0.1/tasks/YOUR_TASK_ID \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
  "task_version": 0,
  "inputs": [
    "promptloop.com"
  ]
}'
```

**Response**

```bash Response theme={null}
{
  "status": "success",
  "data": {
    "job_id": "6497b030-f841-4421-ab39-7e0c16e83ee6",
    "error_detected": false,
    "list": false,
    "data_json": {
      "Site Description": "PromptLoop is an AI platform for GTM and B2B sales that automates web scraping, deep research, and CRM data enrichment, providing accurate B2B insights to make research 10 times faster.",
      "Contact Email": "team@promptloop.com"
    },
    "list_data_json": null
  },
  "message": "",
  "error": null,
  "request_id": "9e56405e-f910-43ae-ad95-d2d09ad83909"
}
```

<Note>
  Most of the time you will be using Batch APIs - which amount to sending a set
  of inputs like this example at once and receiving a webhook
</Note>

Once you send your first request you are off to a great start!

<RequestExample>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.promptloop.com/v0.1/tasks/YOUR_TASK_ID \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_API_KEY' \
    --data '{
    "task_version": 0,
    "inputs": [
      "promptloop.com"
    ]
  }'
  ```

  Response

  ```bash Response theme={null}
  {
    "status": "success",
    "data": {
      "job_id": "6497b030-f841-4421-ab39-7e0c16e83ee6",
      "error_detected": false,
      "list": false,
      "data_json": {
        "Site Description": "PromptLoop is an AI platform for GTM and B2B sales that automates web scraping, deep research, and CRM data enrichment, providing accurate B2B insights to make research 10 times faster.",
        "Contact Email": "team@promptloop.com"
      },
      "list_data_json": null
    },
    "message": "",
    "error": null,
    "request_id": "9e56405e-f910-43ae-ad95-d2d09ad83909"
  }
  ```
</RequestExample>

## Continued: Core PromptLoop Concepts

<AccordionGroup>
  <Accordion icon="list-check" title="Tasks">
    Tasks are actions for our systems to accomplish for you. They consist of
    inputs (like a website or search item) and return outputs as new columns or
    rows of data.
  </Accordion>

  <Accordion icon="database" title="Datasets">
    Datasets are repositories for your information. You can search, filter,
    save, and share inputs and outputs from AI tasks up to hundreds of thousands
    of rows.
  </Accordion>

  <Accordion icon="table" title="API Endpoints">
    The PromptLoop API lets you launch and monitor jobs to enrich data and
    create Datasets
  </Accordion>
</AccordionGroup>

## Generate and API Access

Teams on PromptLoop enterprise plans can access our core API:

<CardGroup>
  <Card title="API Access" icon="wand-magic-sparkles" href="https://promptloop.com/account/settings">
    Create custom AI-powered content generation workflows.
  </Card>
</CardGroup>

These features can be enabled and managed in your team's settings page.

## Learn More

<CardGroup>
  <Card title="Custom Tasks" icon="wand-magic-sparkles" href="https://promptloop.com/account/custom">
    Learn how to create and modify tasks to suit your needs.
  </Card>

  <Card title="Datasets" icon="database" href="https://promptloop.com/account/datasets">
    Understand how to manage and utilize datasets effectively.
  </Card>

  <Card title="Spreadsheet Integration" icon="table" href="https://promptloop.com/account/settings">
    Explore how to use PromptLoop with Excel and Google Sheets.
  </Card>

  <Card title="Book a Demo" icon="calendar" href="https://promptloop.com/demo">
    Get personalized support for your specific business needs.
  </Card>
</CardGroup>


# Concepts & Capabilities
Source: https://docs.promptloop.com/get-started/task-concepts

Understanding PromptLoop tasks, web browsing capabilities, and the difference between batch and single job processing

## What are PromptLoop Tasks?

**PromptLoop Tasks are no-code AI agents** that take structured inputs (like websites or search terms) and return clean, formatted data at any scale. They're the core building blocks of the PromptLoop platform, designed to automate research that would normally take hours per prospect or company.

### Key Benefits

* **Automate research** that normally takes hours per prospect or company
* **Scale instantly** from a single test row to thousands of data points
* **Keep results consistent** with strict formats, confidence scores, and guardrails
* **Process any format** from millions of company page types using optimized AI models

## Task Types & Capabilities

### 1. Website Tasks

**Best when you have:** A list of URLs\
**What it does:** Crawls websites and extracts specific data points\
**Example use case:** Find pricing information on competitor websites

```json theme={null}
{
  "data_uuid": "1",
  "inputs": ["https://acme-corp.com"]
}
```

### 2. Search Tasks

**Best when you have:** Only a company name or keyword\
**What it does:** Searches for relevant websites first, then crawls them\
**Example use case:** Get LinkedIn URL for "Acme Corp"

```json theme={null}
{
  "data_uuid": "2",
  "inputs": ["Acme Corp"]
}
```

## Web Browsing Capabilities

### Crawl Depth Options

Choose the appropriate browsing depth based on your data requirements:

| Depth                       | How Deep It Goes                            | When to Use                            | Cost     |
| --------------------------- | ------------------------------------------- | -------------------------------------- | -------- |
| **Single Page**             | Only the exact URL provided                 | Data only from that specific page      | Lowest   |
| **Smart Crawl** *(default)* | Follows relevant links a few levels deep    | Most website tasks—fastest & cheapest  | Standard |
| **Deep Research**           | Explores far more pages throughout the site | Hard-to-find info buried deep in sites | Higher   |

### Data Format Options

Tasks support multiple output formats to match your exact needs:

| Format                  | Best For                                 | Example                               |
| ----------------------- | ---------------------------------------- | ------------------------------------- |
| **Text**                | Descriptions & summaries                 | Company descriptions                  |
| **True/False**          | Yes/no checks                            | "Does this company offer API access?" |
| **Number**              | Counts, prices, metrics                  | Employee count, revenue               |
| **Link**                | URLs                                     | Contact page URLs, social links       |
| **Single Category**     | One label from predefined options        | Industry classification               |
| **Multiple Categories** | Multi-label tagging                      | Services offered                      |
| **List**                | Multiple items (creates additional rows) | List of team members                  |
| **JSON**                | Complex structured data                  | Contact information objects           |

## Single Jobs vs Batch Processing

### Single Jobs

**Use case:** Real-time processing, testing, or individual requests\
**How it works:** Send one input, get immediate results\
**Best for:**

* Testing task configurations
* Real-time integrations
* Processing individual records on-demand

**API Endpoint:** `POST /v0/tasks/{id}`

**Example Request:**

```bash theme={null}
curl --request POST \
  --url https://api.promptloop.com/v0/tasks/YOUR_TASK_ID \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "task_version": 0,
    "inputs": ["https://example.com"]
  }'
```

**Response Format:**

```json theme={null}
{
  "status": "success",
  "data": {
    "job_id": "uuid-here",
    "error_detected": false,
    "list": false,
    "data_json": {
      "Company Description": "AI platform for sales teams...",
      "Contact Email": "team@example.com"
    }
  }
}
```

### Batch Processing

**Use case:** Large-scale data processing (hundreds to thousands of inputs)\
**How it works:** Upload JSONL data, monitor progress, retrieve results when complete\
**Best for:**

* Processing entire datasets
* Bulk research operations
* Building comprehensive databases

**API Endpoints:**

* `POST /v0/batches` (launch)
* `GET /v0/batches/{id}` (monitor)
* `GET /v0/batches/{id}/results` (retrieve)

**Input Format (JSONL):**

```json theme={null}
{"data_uuid": "1", "inputs": ["https://example.com"]}
{"data_uuid": "2", "inputs": ["https://another-example.com"]}
{"data_uuid": "3", "inputs": ["https://third-example.com"]}
```

**Batch Workflow:**

<Steps>
  <Step title="Launch Batch Job">
    Submit your JSONL data to start processing multiple inputs simultaneously
  </Step>

  <Step title="Monitor Progress">
    Check job status periodically using the batch ID
  </Step>

  <Step title="Retrieve Results">
    Download completed results once processing is finished
  </Step>
</Steps>

## Input & Output Structure

### Input Requirements

Each task defines specific input requirements:

* **Website tasks:** Valid URLs (e.g., `https://example.com`)
* **Search tasks:** Search terms or company names (e.g., `"Acme Corp"`)
* **Data UUID:** Unique identifier for tracking each input through processing

### Output Structure

Task outputs are structured as key-value pairs:

```json theme={null}
{
  "data_uuid": "1",
  "Company Name": "Acme Corp",
  "Industry": "Software",
  "Employee Count": 150,
  "Has API": true,
  "Contact Email": "contact@acme-corp.com",
  "Technologies": ["React", "Node.js", "AWS"]
}
```

**For List Tasks:** Additional rows are created for each list item:

```json theme={null}
[
  {
    "data_uuid": "1",
    "Company Name": "Law Firm LLC",
    "Partner Name": "John Smith",
    "Partner Title": "Managing Partner",
    "Partner Email": "jsmith@lawfirm.com"
  },
  {
    "data_uuid": "1",
    "Company Name": "Law Firm LLC",
    "Partner Name": "Jane Doe",
    "Partner Title": "Senior Partner",
    "Partner Email": "jdoe@lawfirm.com"
  }
]
```

## Advanced Features

### Search Engine Techniques

Enhance your search tasks with standard search operators:

* `site:domain.com` - Results only from specific site
* `-site:domain.com` - Exclude specific site
* `term1 AND term2` - Results containing both terms
* `"exact phrase"` - Exact phrase matching

### Chained Tasks

Connect multiple tasks in sequence for complex workflows:

1. **Website Discovery:** Find company website from name
2. **Data Extraction:** Extract contact information from website
3. **Social Enrichment:** Find LinkedIn profiles for key contacts

### Webhooks for Batch Processing

Receive real-time notifications when batch jobs complete:

```json theme={null}
{
  "status": "completed",
  "message": "Your data processing is complete",
  "data": [...], // Array of processed results
  "timestamp": "2024-07-23T03:57:20.643Z",
  "batch_id": "12345"
}
```

## Best Practices

### Task Design

* **Focus:** Create tasks for specific purposes and only ask for the data you need
* **Testing:** Use the single job endpoint to test and iterate on task configurations
* **Formatting:** Select the correct output format for each data type to ensure consistency

### Performance Optimization

* Start with **Smart Crawl**, upgrade to **Deep** only if data is missing
* Keep search queries generic (not company-specific) for better consistency
* Use **Categories** for any data you'll filter or group on later

### Error Handling

* Implement proper retry logic for rate limits (429 errors)
* Validate input data using the `/v0/batches/validate-data` endpoint
* Monitor job status regularly for batch processing

## Rate Limits & Constraints

### Batch Limits

* **File size:** 100MB maximum per JSONL upload
* **Processing:** Subject to account usage limits
* **Results:** Use `output_type=stream` for large result sets

### API Rate Limits

* **Single jobs:** 5 TPM for task execution
* **Batch jobs:** 4 TPM for batch creation
* **Monitoring:** 20 TPM for status checks

## Next Steps

<CardGroup>
  <Card title="API Overview" icon="server" href="/get-started/api-overview">
    Learn about authentication, data formats, and API workflow
  </Card>

  <Card title="Quick Start" icon="rocket" href="/get-started/quickstart">
    Run your first task and see results immediately
  </Card>

  <Card title="Create Tasks" icon="plus" href="https://promptloop.com/account/custom">
    Build custom tasks in the PromptLoop dashboard
  </Card>

  <Card title="View Templates" icon="template" href="https://promptloop.com/templates">
    Browse proven task templates for common use cases
  </Card>
</CardGroup>


# Cancel Batch
Source: https://docs.promptloop.com/v0.1/batches/cancel-batch

/openapi-v0.1.json post /v0.1/batches/{batch_id}/cancel
Cancels a running batch. This will mark the batch as cancelled and remove any pending jobs from the queue. Jobs that are already in progress will complete.



# Create Batch
Source: https://docs.promptloop.com/v0.1/batches/create-batch

/openapi-v0.1.json post /v0.1/batches
Uploads a JSONL file and launches a new batch with the provided data. Returns the batch id.



# Get All Batches
Source: https://docs.promptloop.com/v0.1/batches/get-all-batches

/openapi-v0.1.json get /v0.1/batches
Retrieves a list of the high-level metadata for all batches (paginated).



# Get Batch
Source: https://docs.promptloop.com/v0.1/batches/get-batch

/openapi-v0.1.json get /v0.1/batches/{batch_id}
Retrieves detailed metadata for the batch with provided id. This includes the batch status, job count, and other metadata.



# Get Results
Source: https://docs.promptloop.com/v0.1/batches/get-results

/openapi-v0.1.json get /v0.1/batches/{batch_id}/results
Returns raw JSON results for a completed batch. Use a webhook configured on the batch for push delivery.



# Retry Failed Jobs
Source: https://docs.promptloop.com/v0.1/batches/retry-failed-jobs

/openapi-v0.1.json post /v0.1/batches/{batch_id}/retry
Retries failed jobs in a batch. Only jobs currently marked as failed are eligible.



# Update batch metadata
Source: https://docs.promptloop.com/v0.1/batches/update-batch-metadata

/openapi-v0.1.json put /v0.1/batches/{batch_id}
Updates user-defined metadata fields for the batch with provided id. This includes the webhook_url. Explicitly passing an empty string for webhook_url to the request body will remove/clear any webhook url from the batch.



# Validate Batch Data
Source: https://docs.promptloop.com/v0.1/batches/validate-batch-data

/openapi-v0.1.json post /v0.1/batches/validate-data
Uploads a JSONL file and validates the data for a new batch with the provided data. Returns the batch id.



# Create company list export
Source: https://docs.promptloop.com/v0.1/company-lists/create-company-list-export

/openapi-v0.1.json post /v0.1/company-lists/exports
Runs a semantic company search with optional country, business model, and NAICS filters, persists the results as a dataset, and returns a short-lived signed download URL.



# Create Task from Description
Source: https://docs.promptloop.com/v0.1/tasks/create-task-from-description

/openapi-v0.1.json post /v0.1/tasks/create
Creates a new task from a natural language description. AI will generate the task definition based on your description.



# Edit Task with Instruction
Source: https://docs.promptloop.com/v0.1/tasks/edit-task-with-instruction

/openapi-v0.1.json patch /v0.1/tasks/{task_id}
Edits an existing task with a natural language instruction. Creates a new version of the task.



# Get All Tasks
Source: https://docs.promptloop.com/v0.1/tasks/get-all-tasks

/openapi-v0.1.json get /v0.1/tasks
Retrieves a list of the high-level metadata for all tasks.



# Get Task
Source: https://docs.promptloop.com/v0.1/tasks/get-task

/openapi-v0.1.json get /v0.1/tasks/{task_id}
Retrieves detailed metadata for the task with provided id (inputs, outputs, etc.).



# Quick Test Task
Source: https://docs.promptloop.com/v0.1/tasks/quick-test-task

/openapi-v0.1.json post /v0.1/tasks/{task_id}/test
Quickly test a task with a single input. Useful for validating task behavior before running on full datasets.



# Run Dynamic Task
Source: https://docs.promptloop.com/v0.1/tasks/run-dynamic-task

/openapi-v0.1.json post /v0.1/tasks
Runs the dynamic research task with custom queries. Provide a website URL and a list of queries with optional formatting guidance and the task will return the enriched results.



# Run Single Job
Source: https://docs.promptloop.com/v0.1/tasks/run-single-job

/openapi-v0.1.json post /v0.1/tasks/{task_id}
Runs a single job with the provided task and inputs and awaits the result. Tasks have a default timeout of 1 minute. For longer running tasks, consider using async batches instead.



# Get Team Limits
Source: https://docs.promptloop.com/v0.1/team/get-team-limits

/openapi-v0.1.json get /v0.1/team/limits
Retrieves plan limits and configuration for the team including row limits, rate limiting status, and subscription details.



# Get Team Usage
Source: https://docs.promptloop.com/v0.1/team/get-team-usage

/openapi-v0.1.json get /v0.1/team/usage
Retrieves usage statistics for the current billing period including rows processed, credits used, and credits remaining.