# Infinite Intent

> Run an intent-driven audience programme, follow the run's progress and open the interactive results page in your browser.

Canonical guide: <https://engine.neraperla.com/docs/infinite-intent>

Raw Markdown: <https://engine.neraperla.com/docs/raw/infinite-intent.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

## Use Infinite Intent

In a connected Claude session, say:

```text
Find leads for World of Claudecraft using Infinite Intent.
```

or upload an intent file and describe the activation, for example:

```text
Attached is an intent file of people registering interest in "coastal retreat"
keywords. Which part of the list should get "Book Now" discount offers?
```

Two programmes exist today. `world-of-claudecraft` delivers the World of
Claudecraft audience report from the configured audience dataset, intent
signals, recorded contact checks and qualification notes. `coastal-retreat`
activates a client-supplied intent file of hashed emails (HEMs) against the
coastal-retreat intent graph and scores each identity on the L0–L4 purchase
funnel. A programme must be enabled for the key's project. Research dates
describe the underlying data; run timestamps describe delivery of the page.

Connected Claude sessions using the Blackpearl custom connector can start runs
with the `run_infinite_intent` tool (passing the uploaded file's name and row
count) and poll with `get_job_status`; API-key sessions use the endpoints below.

## Agent procedure

1. Reuse the session's working `BLACKPEARL_API_KEY`. If connection is needed,
   follow [agent setup](https://engine.neraperla.com/docs/agent-setup). Do not display the key.
2. Check `GET /v1/capabilities` for `infinite_intent` with `enabled: true`; the
   capability description names the programmes enabled for this project.
   Start immediately when the user requests an enabled programme;
   no extra interview, planning approval or skill installation is needed.
   If absent, explain that this project needs access; do not replace keys or
   substitute a paid capability.
3. When the user uploaded an intent file, count its data rows and pass
   `audience_file` with the filename and hashed-email count — progress
   milestones echo them. Never paste file contents into the request, and do
   not analyze the file locally: hashed email identifiers carry no readable
   signal, so segments and geography cannot be derived from the file itself.
   Do not ask clarifying questions before starting — the completed report
   contains the funnel, segment and geography breakdowns that answer
   targeting questions.
4. Use a unique `Idempotency-Key`, POST below, save the job ID and announce the run.
5. Poll `infinite_intent_events` at `events_url?after_seq=0` every 3 seconds; use
   `next_after_seq`. Share new milestone messages while the run progresses.
   Avoid hiding the whole run inside one long, silent command.
6. Continue through `queued` and `running`. On `succeeded`, retrieve
   `status_url` to get `result`. On `failed` or `canceled`, stop and report the
   status/error. The response's `estimated_duration_seconds` is the target
   execution time (277 seconds for `world-of-claudecraft`, about 10 seconds for
   `coastal-retreat`); queueing/deployments can add time.
7. **Open `result.report_url` in a new browser tab** using the client's browser
   tool or supported desktop URL opener. Give the user a clickable **View leads**
   link; do not download or recreate HTML. If this Claude client cannot open browser tabs, present that link and
   say it is ready to open; never claim a tab opened without tool confirmation.

### Start a run

Operation: `create_infinite_intent`. Accepted scenarios are
`world-of-claudecraft` and `coastal-retreat`; do not imply a different audience
was researched.

```bash
curl --fail-with-body --silent --show-error --request POST \
  "$BLACKPEARL_API_BASE_URL/v1/infinite-intent" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $INFINITE_INTENT_RUN_ID" \
  --data '{"scenario":"world-of-claudecraft"}'
```

For an intent-file activation, include the file summary:

```bash
curl --fail-with-body --silent --show-error --request POST \
  "$BLACKPEARL_API_BASE_URL/v1/infinite-intent" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $INFINITE_INTENT_RUN_ID" \
  --data '{"scenario":"coastal-retreat","audience_file":{"filename":"coastal-retreat-intent-hems.csv","hashed_email_count":9847}}'
```

Accepted response (truncated):

```json
{"id":"job_123","type":"infinite_intent","status":"queued","result":null}
```

On completion, `GET /v1/jobs/{job_id}` returns `result.report_url`,
`report_url_expires_at`, title, `lead_count`, source and export metadata.

### Access, usage and resuming

The hosted page requires the designated viewer's Blackpearl browser login.
Signed-out visitors sign in and return to the page; other accounts receive 404.
The URL grants no access by itself. Legacy share tokens no longer grant access.
Claude's API key does not sign the browser in. Availability ends at the job's
30-day retention deadline (`report_url_expires_at`).

`billing.actual_charge_usd` and `billing.credits_used` are the actual charge and
credits deducted, currently zero for this programme. Do not infer a charge from
lead counts. Billing status moves from `reserved` to `settled` on success or
`released` on failure/cancellation. `/v1/usage` retains actual request counts and
the existing account balance.

To cancel, call `cancel_infinite_intent`: `POST /v1/infinite-intent/{job_id}/cancel`;
repeating it is safe. For an explicitly requested HTML export, use authenticated
`infinite_intent_artifact`: `GET /v1/infinite-intent/{job_id}/artifact`.

### Errors

- 401: missing, invalid or revoked API key; follow [authentication](https://engine.neraperla.com/docs/authentication).
- `capability_disabled` (403): the key's project needs access; do not retry blindly.
- `invalid_request` (400/422): fix the scenario or required Idempotency-Key.
- `conflict` (409): another run is active. Resume `error.details.job_id`.
- `idempotency_in_progress` (409): retry the same POST/key shortly.
  `idempotency_key_reused` (409): the same key was used for different input.
  Identical retries reuse the job for 24 hours and return its current state.
- `job_not_finished` (409): the export is available only on success.
- `rate_limit_exceeded` (429): honor `Retry-After`. `quota_exceeded` (429)
  requires resolving the request quota.
- Unknown or cross-project jobs return 404. Jobs, events and exports expire
  after 30 days with `job_expired` (410). The hosted page returns 410 to its
  authorized viewer after retention; other signed-in accounts always receive 404.
- Network errors/5xx: use bounded backoff and preserve the job ID/idempotency key.
  Disconnecting does not cancel the run; restarts resume the persisted timeline.
  After ten minutes of polling, report the current state and retain the ID for
  resumption. Do not silently start another run.

See [jobs](https://engine.neraperla.com/docs/jobs), [errors](https://engine.neraperla.com/docs/errors) and [usage](https://engine.neraperla.com/docs/usage-quotas).
