Skip to content

Docs / All tools / Loop II: Acquisition

icp.job_status

Check the progress of an ICP search and retrieve its results.

0 credits. Free: status read.

Example prompt

Send this to your AI app when Heelo is connected:

Check on my ICP search

Input fields

FieldTypeDescription
job_idRequiredstringThe job_id returned by icp.search
limitintegerMax companies to return (default 100)
offsetintegerPagination offset into the ranked list
include_claimsbooleanInclude the full per-field provenance for each company. Verbose — use only when auditing where a value came from.

Output fields

The fields in data when status is success.

FieldTypeDescription
answerstring
duration_snumber
job_idstring
statusstring
phasestring
phase_labelstring
progressobjectThe counts of the run. `sources_read` is the number of discovery sources that the job tried. When the job has finished, `errors` holds a count per error code for what failed without failing the job: one final code per discovery source (none if a read found companies, so a source that only the browser could read has none), one per company that could not be read, and one if the web search could not run. For example, `source_unavailable` counts a company's site or a source that could not be read, and a source that lost its browser render and kept what plain HTTP found.
cost_centsinteger
companiesarray of objectThe companies, best first (for small local businesses, the ones with an address come first). Each has: name, domain, rank, contact_name, contact_position, persona_match, contact, geography, employee_number, size_confirmed, company_type, funding_stage, recent_funding, valuation, found_via, fit_score, status. size_confirmed is null when the search asked for no size range, false when the headcount is unknown, unparseable or only a team-page count, and true when a stated count or band backs it. persona_match is true when the contact's title holds one of the spec's contact_titles (read by a reranker), false for a fallback such as a founder or CEO, and null when there is no contact, no title was asked for, the reranker failed, or the title matches but the employer check gave no answer for it (unknown).
completeboolean
ranking_finalboolean
estimateobject
retry_after_sinteger
next_actionstring
errorstring

Code

The call with the input fields that the tool needs. Replace each word in capitals, such as JOB_ID. Set HEELO_API_KEY to your API key.

import os
import requests

response = requests.post(
    "https://toolsprimitives.uk/v1/tools/icp.job_status/invoke",
    headers={"Authorization": f"Bearer {os.environ['HEELO_API_KEY']}"},
    json={"input": {
        "job_id": "JOB_ID",
    }},
    timeout=120,
)
response.raise_for_status()
print(response.json())