Infinite Intent

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

Use Infinite Intent#

In a connected Claude session, say:

Find leads for World of Claudecraft using Infinite Intent.

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

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. 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.

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:

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):

{"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.
  • 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, errors and usage.