Endpoints // Bulk

Task history

New

Last verified November 4, 2026

Read every task of your workspace, newest first, whoever started it, from the API, an AI assistant or the app, with filters by type, status and List, for free.

GET/v2/tasks

Credits

Free.

Introduction

The Task history endpoint returns the background tasks of your workspace, newest first: the tasks of Bulk enrichment, and the tasks that run the same way in the app or through a List, such as a List import or a Search exported as a file. It covers every task, whoever started it: an API key, an AI assistant through the MCP server, Ask or a member of your team in the app. Each item has the fields of Get a task.

This endpoint is free (0 credits), also at a zero balance. It counts toward your per-minute rate limit like any other call.

A key sees the tasks its permissions allow: Person Enrichment or Contact for the enrich_persons tasks, Lists for the List tasks, Search for the Search exports. A key with no matching permission gets an empty page.

Authorization

Name	Type	Required	Description
`apikey`	string	Yes	Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header.

Query Parameters

Name	Type	Required	Description
`type`	string	No	Only these types, comma-separated, see Task types
`status`	string	No	Only these statuses, comma-separated: `queued`, `running`, `paused`, `completed`, `cancelled`, `failed`
`listId`	string	No	Only the tasks of this List (UUID)
`perPage`	integer	No	Tasks per page, from 1 to 100. Defaults to 50.
`cursor`	string	No	The `nextCursor` of the previous page, sent with the same filters. A malformed cursor, or one sent with other filters, returns `400`.

The route is GET /v2/tasks. A type or status that is not in its list returns 400 TASK_INVALID_INPUT with the accepted values.

Task types

`type`	What the task does
`enrich_persons`	Looks up people and returns a CSV: Bulk enrichment, or a file enriched with Bulk Import in the app
`list_import`	Imports Signals or a file into a List: Import members and data
`list_enrich`	Buys data for the members of a List
`list_search_import`	Adds the results of a Search to a List
`search_export`	Exports the results of a Search as a file

Only an enrich_persons task has a results CSV at Download task results. The members of a List task are read with List members, and its links.operation is the List operation it runs as.

Response structure

Field	Type	Description
`success`	boolean	`true` if the request was processed successfully
`error`	`null`	Always `null` on success

dataobject

One page of tasks

Show child attributes

Field	Type	Description
`items`	Task	The tasks of this page, newest first, with the fields of Get a task
`nextCursor`	string \| null	Send it back as `cursor` for the next page, `null` on the last page

quotas and metadata are the blocks of every V2 response: see Usage.

Errors

Status	Code	Meaning
`400`	`TASK_INVALID_INPUT`	An unknown `type` or `status`, a `perPage` out of range, or a cursor that is malformed or sent with other filters
`422`	`VALIDATION_ERROR`	`listId` is not a UUID

Code examples

Remembered on every page

Code Examples

curl "https://api.reversecontact.com/v2/tasks?type=enrich_persons&status=completed,cancelled" \
  -H "Authorization: Bearer YOUR_API_KEY"

const headers = { "Authorization": "Bearer YOUR_API_KEY" };
const tasks = [];
let cursor = null;

// Read every completed or cancelled task, page by page.
do {
  const query = new URLSearchParams({ type: "enrich_persons", status: "completed,cancelled", perPage: "100" });
  if (cursor) query.set("cursor", cursor);
  const response = await fetch(`https://api.reversecontact.com/v2/tasks?${query}`, { headers });
  const { data } = await response.json();
  tasks.push(...data.items);
  cursor = data.nextCursor;
} while (cursor);

for (const task of tasks) console.log(task.taskName, task.status, task.credits.used);

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"type": "enrich_persons", "status": "completed,cancelled", "perPage": 100}
tasks = []

while True:
    data = requests.get("https://api.reversecontact.com/v2/tasks", headers=headers, params=params).json()["data"]
    tasks.extend(data["items"])
    if not data["nextCursor"]:
        break
    params["cursor"] = data["nextCursor"]

for task in tasks:
    print(task["taskName"], task["status"], task["credits"]["used"])

Example response

200 - Success

Example Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "7b1e4c2a-5d3f-4e8b-9a6c-1f2d3e4b5a60",
        "type": "enrich_persons",
        "entity": "persons",
        "status": "completed",
        "source": "api",
        "taskName": "CRM export, November",
        "listId": null,
        "progress": { "total": 2, "processed": 2, "succeeded": 2, "failed": 0, "skipped": 0, "remaining": 0 },
        "credits": { "estimated": 9, "used": 6 },
        "estimatedSecondsRemaining": null,
        "error": null,
        "createdAt": "2026-11-04T09:30:00.000Z",
        "startedAt": "2026-11-04T09:30:01.000Z",
        "completedAt": "2026-11-04T09:31:12.000Z",
        "links": {
          "self": "/v2/tasks/7b1e4c2a-5d3f-4e8b-9a6c-1f2d3e4b5a60",
          "results": "/v2/tasks/7b1e4c2a-5d3f-4e8b-9a6c-1f2d3e4b5a60/results",
          "operation": null
        }
      },
      {
        "id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
        "type": "list_import",
        "entity": "persons",
        "status": "running",
        "source": "dashboard",
        "taskName": "Trade show leads.csv",
        "listId": "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40",
        "progress": { "total": 500, "processed": 120, "succeeded": 114, "failed": 6, "skipped": 0, "remaining": 380 },
        "credits": { "estimated": 0, "used": 456 },
        "estimatedSecondsRemaining": 240,
        "error": null,
        "createdAt": "2026-11-04T09:12:00.000Z",
        "startedAt": "2026-11-04T09:12:02.000Z",
        "completedAt": null,
        "links": {
          "self": "/v2/tasks/c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
          "results": null,
          "operation": "/v2/lists/3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40/operations/c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f/progress"
        }
      }
    ],
    "nextCursor": null
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4528, "left": 5472 }
    }
  },
  "metadata": {
    "requestId": "527e1f57-3514-4080-a649-adb2983ffb0f",
    "executionTimeMs": 44
  }
}