client.jobs

Read or wait for a live fetch or contact job by its saved webhook id.

Calling conventions

Examples assume RC_API_KEY is set. Replace example ids with ids returned by your own requests. Signatures show the published 0.3.0 synchronous methods. Use the same arguments with the Python async client.

models refers to reversecontact.types. NOT_GIVEN and NotGiven are the SDK's internal markers for omitted arguments. Leave these arguments out of your calls. For API body parameters, passing None sends an explicit null. Transport options use None to inherit their defaults. Timeout means a number of seconds or httpx.Timeout. Supply parameters marked Required to Python or to the API, even when the generated signature permits omission.

JSON response objects expose data, quotas, metadata and http_response. Check optional fields for None. See First call for the response envelope. CSV methods return text and iterators yield items.

HTTP failures raise an APIError subclass based on the response: BadRequestError, AuthenticationError, InsufficientCreditsError, PermissionDeniedError, NotFoundError, ConflictError, GoneError, UnprocessableEntityError, RateLimitError, DailyLimitError, KeyCreditLimitError, UnavailableForLegalReasonsError or InternalServerError. See the error mapping and retry rules.

For Bulk job ids, use client.bulk. For List operation ids, use client.lists.

retrieve

Read the current job state with client.jobs.retrieve(). See Polling for details.

def retrieve(
    webhook_id: str,
    *,
    wait: int | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.PollWebhookData]: ...

Parameters

Returns

Result[models.PollWebhookData]. data is one job snapshot, including status, error_code, result, delivery_status and credits_consumed. result is decoded JSON. An errored job is returned without raising JobFailedError.

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid SDK options or a wait outside the integer range 0 to 20. Malformed typed response data can raise Pydantic ValidationError.

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.jobs.retrieve("00000000-0000-4000-8000-000000000001", wait=20)
    print(result.data if result is not None else None)

wait

Wait for the job to finish with client.jobs.wait(). See Polling for details.

def wait(
    job_id: str,
    *,
    timeout: float = 1800,
    poll_wait: int = 20,
    on_poll: Callable[[Result[JobSnapshot[object]]], None] | None = None,
    headers: Mapping[str, str] | None = None,
) -> Result[JobSnapshot[object]]: ...

Parameters

Returns

Result[JobSnapshot[object]]. data is the successful job snapshot. data.result is decoded JSON and does not use the original job handle's typed result parser. No new enrichment job is created.

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid poll_wait or timeout. wait() raises JobFailedError for an errored job and JobTimeoutError when its overall deadline expires. Malformed typed response data can raise Pydantic ValidationError.

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.jobs.wait("00000000-0000-4000-8000-000000000001")
    print(result.data if result is not None else None)

Related guides

See the Python SDK overview, Async jobs, Fetch and Contact.