Give your assistant the contract

pineapi — LinkedIn profile extraction over HTTP. You are driving it for me.
Base URL: ask me for PINEAPI_BASE_URL; the production API host is not yet confirmed.
Do not send credentials to the website or guess an API hostname.
Auth: Authorization: Bearer <my key, starts pine_sk_>. Keep the key private.
Cost: $0.012 per profile delivered, prepaid. Search minimum $0.12; lookup no floor.
Never request more than I asked for. Explain the maximum cost and ask before a run over $5.
No sandbox, test credit, free trial, email enrichment or MCP server.

Both creation POSTs require an Idempotency-Key and return 202 with run_id.
Generate a unique key for each new operation; persist it with the exact body.
For a retry of the same operation, reuse that key and unchanged body.

1. Search: POST /v1/profile-searches
{"locations":["Spain"],"current_job_titles":["Data Engineer"],"max_items":100}
max_items: multiple of 25, from 25 to 2000, default 100.
Read closed vocabularies, do not guess values:
GET /v1/catalogs/industries, /locations, /schools, /experience-bands,
/company-headcounts. Experience bands apply to years_of_experience and
 years_at_current_company; headcounts apply to company_headcount.

2. Lookup: POST /v1/profile-lookups
{"linkedin_urls":["https://www.linkedin.com/in/<slug>"]}
1–2000 URLs, normalized and deduplicated; no blocks of 25 or search floor.

Poll GET /v1/runs/{run_id} until succeeded, partial, failed or cancelled.
Poll every 5 seconds for the first minute, then every 20 seconds.
Lookup usually takes seconds, search minutes. These are not deadlines or an SLA.
Queued, starting, running and processing are not final. Preserve run_id on timeout.
Read /v1/runs/{run_id}/profiles?limit=50; pass next_cursor as cursor unchanged
until has_more is false. No offset. CSV: /v1/runs/{run_id}/profiles.csv.

Report profiles_delivered, charged, status and unresolved[] from the run.
Match lookup rows to inputs by requested_url, never the current linkedin_url slug.
Unresolved not_found: dead/renamed URL; unavailable: worth retrying later.
Unresolved URLs cost nothing. Separate runs may bill the same profile again.
Within one run a duplicate row is not delivered or charged twice.
Partial is a normal terminal outcome: fewer profiles arrived than requested.
experience_truncated / skills_truncated flag incomplete source sections;
total_months_experience can therefore be an undercount. No email addresses.
start_page is unstable search pagination; prefer one appropriately sized run.
Results expire after 30 days. Save lawful copies before expiry.

Errors: {"error":{"type":"…","code":"…","message":"…","param":null}}.
401 missing_api_key / invalid_api_key: stop and ask for a valid credential.
403 insufficient_scope: ask for a key with the required scope; do not retry blindly.
422 invalid_parameter / start_page_out_of_range: correct the named input.
402 insufficient_balance: stop and ask me to top up; minimum top-up $5.
429: wait Retry-After seconds before retrying; retain the idempotency key/body.
409 idempotency_key_reused: do not change the body of an existing operation.
Missing Idempotency-Key is rejected: add it before starting a new operation.
For transient HTTP failures, retry cautiously with the same key/body.
Poll authenticated run status; webhook signing-secret access is not yet available.