API overview

The API is organized around actions and runs. Submit an action with a bounded input; inspect the run and its output using the returned ID. API paths are versioned under /v1.

Download the OpenAPI specification for the machine-readable HTTP contract.

Base URL and headers

Use the API host configured for your workspace. The examples use $API_URL for that host, without the /v1 suffix. Requests and responses use JSON.

http

Authorization: Bearer YOUR_SECRET_API_KEY
Content-Type: application/json
Idempotency-Key: a-unique-work-item-001

The idempotency header is required on action submissions. It is not needed for read requests.

Data actions

All 16 actions support POST /v1/actions/{action}/run/live and POST /v1/actions/{action}/run/async.

Action	Required input	Credit cost
Standard person lookup	`first_name`, `last_name`, `company`; optional `linkedin_profile_url`	1 per match
Search people	`keywords`	1 per result
Search company employees	`company`; optional `keywords`	1 per result
Count search results · metrics	`company` or `keywords`	1 per query
Search accounts · Sales Navigator	`keywords`	1 per result
Search companies	`keywords`	1 per result
Search schools & universities	`query`	1 per result
Search groups	`query`	1 per result
Extract school alumni	`school`; optional `keywords`	1 per result
Extract group members	`group_id`	1 per result
Enrich a profile	`identifier`	20 per result
Enrich a company	`identifier`	1 per result
Get profile posts	`identifier`	1 per result
Search posts	`keywords`	1 per result
Get post comments	`social_id`	1 per result
Get post reactions	`social_id`	1 per result
Get the current registry with the public `GET /v1/actions` route. It returns an `actions` array with each action's `id`, `input_key`, `credits_per_record`, and `max_results`.

Connect actions together

Enrich a profile with its public handle or LinkedIn URL.
Copy output[0].linkedin_profile_identifier into the profile-posts action’s input.identifier.
Copy a returned post’s social_id into the comments or reactions action’s input.social_id. Post search returns the same input field.

The source may return a share, ugcPost, or activity social ID. Pass it exactly as returned. These are public LinkedIn resource identifiers. They are distinct from the numeric member ID and activity ID. The API does not return provider account IDs or credentials.

Run management

Method	Path	Purpose
GET	`/v1/runs`	Latest 100 workspace runs
GET	`/v1/runs/{id}`	Run state, output, and accounting
GET	`/v1/runs/{id}/outputs`	Output array, state, and completeness
POST	`/v1/runs/{id}/cancel`	Request cancellation

Run IDs are UUIDs and are scoped to the authenticated workspace. There is no run-list pagination or webhook delivery in the current release.

Workspace and key management

Method	Path	Purpose
GET	`/v1/workspace`	Workspace, credits, reservations, and today's usage
GET	`/v1/keys`	List key metadata
POST	`/v1/keys`	Create a key from `{ "name": "Integration name" }`
DELETE	`/v1/keys/{id}`	Revoke a key; returns 204

Key management requires an account session. Creating a key returns { id, api_key, prefix, name, created_at }. Listing keys returns { keys: [...] } without secrets.

Common run response

id, action, and status identify the work. output is always an array; enrichment actions still use a one-element array. credits_used is the final customer cost, while credits_reserved is the outstanding reservation. The response also includes timestamps and completeness.

completeness.scope is currently single_page. has_more: true is a source signal, not a continuation cursor. Do not loop the same request expecting subsequent pages.

Response handling

HTTP 202 means the run is still queued or processing. HTTP 200 means the API returned a terminal run; its status can still be failed. Inspect the response body before treating the extraction as successful.

See runs and retries, errors, and the individual action references for complete integration behavior.