client.tasks

Read or wait for the async tasks started by live fetches and contact lookups.

Create client by following Install and configure. The examples use a saved taskId from the relevant task family. The @reverse-contact/sdk package exports Body, Data, Query and the other types used in the signatures.

JSON responses contain data and optional quotas and metadata. They also include the original response, with its body already read. See First call for response handling.

HTTP errors use the APIError subclasses and retry rules: BadRequestError, AuthenticationError, InsufficientCreditsError, PermissionDeniedError, NotFoundError, ConflictError, GoneError, UnprocessableEntityError, RateLimitError, DailyLimitError, KeyCreditLimitError, UnavailableForLegalReasonsError and InternalServerError, according to the API response. Other statuses use APIError.

client.tasks reads the tasks of live fetches and contact lookups at /v2/webhooks/:webhookId. Bulk enrichment tasks, under /v2/tasks/:taskId, use client.bulk. The Task returned by a live fetch or contact lookup also has task.retrieve() and task.wait() methods. See Async tasks.

From SDK 0.4.0, client.tasks, Task, TaskFailedError and TaskTimeoutError replace client.jobs, Job, JobFailedError and JobTimeoutError. The former names remain as deprecated aliases of the same objects, so existing code and instanceof checks keep working, and the errors also expose jobId with the value of taskId.

retrieve()

Read the current state of an async task. Use the webhookId from a live fetch or contact lookup, not a background Bulk task id.

client.tasks.retrieve<T = unknown>(
  id: string,
  params?: {
    wait?: number;
  },
  options?: RequestOptions
): Promise<Result<TaskSnapshot<T>>>

Parameters

Returns

Result<TaskSnapshot<T>> with data.status, data.result and data.creditsConsumed. You can inspect the snapshot even when the task has failed. Use wait() to raise an error on task failure.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const snapshot = await client.tasks.retrieve(taskId, { wait: 20 });
console.log(snapshot.data.status, snapshot.data.result);

wait()

Resume waiting for a saved live-fetch or contact task without submitting another paid lookup. The generic T describes the result type. The SDK does not validate the profile shape.

client.tasks.wait<T = unknown>(
  id: string,
  options?: WaitOptions<TaskSnapshot<T>>
): Promise<Result<TaskSnapshot<T>>>

Parameters

Returns

Result<TaskSnapshot<T>> once data.status is succeeded. A failed task raises TaskFailedError instead.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response. Waiting raises TaskFailedError for an errored task and TaskTimeoutError when the overall deadline expires.

Example

const done = await client.tasks.wait(taskId, { timeout: 30 * 60 * 1000 });
console.log(done.data.result, done.data.creditsConsumed);

Related guides

Async tasks, client.bulk, Timeouts and cancellation. Return to the TypeScript SDK overview.