Runs

A run is one asynchronous job: discovery, import, monitor or export. A start operation returns 202 with a run in the status queued. The work continues after the response. Read the run with get_run until it has a final status. A queued or running status does not mean that the work is complete.

The run object

{
  "id": "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a",
  "kind": "export",
  "campaign_id": "3f2b8a4e-1c5d-4e7f-9a0b-6c2d8e1f4a7b",
  "monitor_id": null,
  "status": "succeeded",
  "skipped_reason": null,
  "trigger": "manual",
  "created_at": "2026-09-23T12:00:00.000Z",
  "started_at": "2026-09-23T12:00:00.000Z",
  "finished_at": "2026-09-23T12:00:09.000Z",
  "progress": {
    "target": 120,
    "queued": 0,
    "completed": 120,
    "discarded": 0
  },
  "result": {
    "completed": 120,
    "discarded": null,
    "download_url": "https://example.com/exports/accounts.csv",
    "download_expires_at": "2026-09-23T13:00:09.000Z"
  },
  "error_code": null,
  "error": null
}

Run kinds

Credits

Signal charges credits for each action that a run takes, not for each run. These are the prices:

A monitor sends one search query for each watched record and each signal type in its config.

Send get_me to read the balance before you start a run. Signal also checks the balance while a run works, and stops the run when the credits run out. A start with no credits gives 402. Read Start rules.

Run statuses

A run has one of six statuses. succeeded, failed, canceled and skipped are final.

Signal stops a discovery, import or monitor run that stays queued for 2 hours after its start time, or that shows no activity for 2 hours. The run then gets the status canceled, or succeeded when it produced output. A canceled run keeps the records that it added before the cancel.

Cancellation keeps completed records and the credits already used. While cancellation stops the worker, finished_at can remain null. Deleting a campaign or monitor removes API access to its run history. See Cancel rules.

Error codes

error_code is a stable value. Use it in your code.

Progress and result

progress holds the queue counts while the run works:

result holds the final counts of a finished run. The fields that apply depend on the kind:

Start rules

A start returns 202 with a queued run. Each job reference owns its request and result rules:

• Discovery: start_discovery.
• Import: start_import and upload_import.
• Export: start_export.
• Monitors: run_monitor.

A paid start with no credits gives 402 and starts no run. See Errors.

Cancel rules

• cancel_run cancels a run that is queued or running. The run gets the status canceled.
• A run that is already finished gives 409.
• An export run cannot be canceled. cancel_run on an export run gives 409.
• After cancel_run, finished_at stays null until the run stops. Read the run again with get_run to get the end time.
• delete_monitor cancels the active runs of the monitor. delete_campaign cancels active runs of discovery and import configurations that it removes. Independent monitors continue.
• Explicit monitor deletion makes its runs unreadable. Source campaign deletion retains monitors and their runs.

Export download

See the Export reference.

List and poll

list_runs lists the runs of the organization, newest first. It takes the filters campaign_id, kind, status, created_after (at or after) and created_before (before). The time filters are RFC 3339 strings. The list shows the stored status. get_run gives the current status of one run.

Poll get_run every 15 seconds, for at most 240 attempts (60 minutes). If the run stays active, send cancel_run when supported and contact support with its ID. Stop when the status is final. The campaign field active_run_ids lists the discovery, import and monitor runs that are queued or running.

Operations

Each path below follows $LINKT_API_URL/v2. Set LINKT_API_URL to the origin only, for example https://api.signal.linkt.ai.

curl --fail-with-body --request GET "$LINKT_API_URL/v2/runs/$RUN_ID" \
  --header "x-api-key: $LINKT_API_KEY"

curl --fail-with-body --request GET "$LINKT_API_URL/v2/runs?limit=5" \
  --header "x-api-key: $LINKT_API_KEY"

Related

• Create a campaign and discover accounts
• Import accounts or people
• Export data
• Paginate and handle errors
• API reference

Correlate import rows

POST /v2/runs/import accepts 1 to 1,000 JSON rows. Import research and qualification use the campaign criteria. Each row has a zero-based index. Optional external_id keeps your original string, including leading zeroes. Duplicate and empty external IDs are valid. Use row_index to distinguish repeated rows.

{
  "campaign_id": "01950000-0000-7000-8000-000000000001",
  "entity_type": "person",
  "rows": [
    {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com",
      "external_id": "001",
      "account_id": "01950000-0000-7000-8000-000000000002"
    }
  ]
}

Accounts accept name, website, domain, and linkedin_url. People also accept first_name, last_name, email, and title. Extra fields remain research input. linkedin_url maps to the stored LinkedIn field. external_id never affects identity matching. Server-owned fields such as row_index, signal_id, and parent_id do not set internal context.

A person can name an existing account with account_id. The account must belong to your organization. Signal adds an account copy to the campaign when needed and keeps that account as the person's parent during research. A missing, foreign, deleted, or unavailable account produces account_not_found.

Missing names, invalid field types, malformed CSV, and invalid file envelopes return 422 before a run starts. These requests have no row outcomes. Research, qualification, account lookup, and persistence failures after admission produce row outcomes.

Retrieve outcomes

Read GET /v2/runs/{run_id} until result.import_rows.availability is ready. Then call list_import_rows with GET /v2/runs/{run_id}/rows?limit=25. Pages contain at most 100 rows, in ascending row_index order. Send next_cursor to retrieve the next page. A cursor belongs to one run and one organization.

{
  "data": [
    {
      "row_index": 0,
      "external_id": "001",
      "entity_type": "person",
      "status": "matched",
      "signal_id": "01950000-0000-7000-8000-000000000003",
      "reason_code": null
    }
  ],
  "next_cursor": null
}

curl --fail-with-body --request GET "$LINKT_API_URL/v2/runs/$RUN_ID/rows?limit=5" \
  --header "x-api-key: $LINKT_API_KEY"

created means the row creates a public identity. matched means the row resolves to an existing public identity. Both return signal_id. Identity matching uses the current name and secondary-identifier rules across campaigns. A repeated row can match an identity created by an earlier row. Additional researched records cannot replace the input record's result. Conflicting input candidates produce ambiguous_input_entity.

rejected returns signal_id: null and a stable reason_code:

A saved copy whose identity is temporarily unresolved keeps outcomes pending for recovery. GET /rows returns 409 import_rows_pending while the import runs or outcomes are incomplete. A cancellation flag alone does not finalize rows. Failed and canceled imports retain saved successes after worker termination is confirmed. Retries recover saved copies and preserve final outcomes. Row outcomes survive queue expiry.

Historical imports have availability: "unavailable". Their row endpoint returns 409 import_rows_unavailable. Signal does not invent historical row mappings. A run of another kind returns 422 not_import_run. Final import counts come from row outcomes: completed equals created plus matched; discarded equals rejected.