Projects and identities

Projects

• Personal: your own logins (several accounts a site, one of them the default), saved and scheduled tasks, inbox and site settings. It's where you are when you sign in, in the app or from an AI tool.
• Default: the shared project every organization starts with, for running tasks for your product's own users. No one's personal logins and no saved tasks there: each end user is an identity. A task with no identity gets a fresh browser of its own, and nothing of it is kept.
• Projects of your own (made by an organization's admins): shared projects like Default, one per further product or customer, so each keeps its own identities, API keys and spend.

Switch in the app's project switcher, or with switch_project (no argument lists them; signed in with OAuth, your choice is remembered for your next connections; with an API key it lasts for that connection). Each organization API key belongs to one shared project, picked when it's made and movable later.

Identities

An identity (idn_…) is one of your end users. pilotfish keeps, on its servers, their logins for any number of sites (several accounts a site), their signed-in sessions, a residential IP in their country (the same region every time, kept sticky) and their device fingerprint. None of it is handed back: you see only its id, label, your own user id for it, its country and device OS, masked usernames, credential ids and what its tasks cost.

• Create, list, get, update and delete them with the identities tool or /identities.
• Run a task as one with browser_task and identity; a follow-up keeps it. One task at a time per identity.
• Deleting one wipes its logins, sessions and device for good. Its tasks and their costs stay, for your billing.

Getting a user's logins in

Each saved login gets a credential id (cred_…). A password never passes through an AI:

1. A login link. identities with login_link (or POST /identities/:id/link) gives a one-time page, valid for 30 minutes. Your user types their own login there.
2. Your own server. POST /identities/:id/credentials with your API key, from your backend. The MCP refuses it.
3. During a task. With save_logins on, a sign-in typed in one of its tasks is kept once it works.

Use them with credentials: ["cred_…"], or name the account per site with accounts: {"linkedin.com": "work"}.

Which account a task uses

When a site has several saved accounts, a task takes the one the request names, else the one the session already chose, the one your words name, the site's default, or the only one. Otherwise it asks once, at the start: each account, Use another login, Create a new account or Go without signing in. Scheduled runs never ask: they take the default, else the main account.

Cost per task and per user

Every browser_task and follow_up result ends with its cost by kind and where it ran:

SUCCESS
Result: Applied to 3 roles: …
Job: job_Ab12… · 14 steps
Cost: $0.0213 (model $0.0081, residential IP $0.0104, browser $0.0020, CAPTCHA $0.0008)
Project: Acme HR app (prj_acme)
Identity: idn_7Hq2…
Open in pilotfish: https://…/tasks/job_Ab12…

GET /identities/:id/usage gives each identity's totals and its tasks, so you can bill your own users.

Lists page by cursor: GET /identities and GET /jobs take limit (1 to 200, default 50) and return nextCursor; pass it as cursor for the next page (null on the last). The same externalUserId twice gives the existing identity back; changing one to an id another identity has is 409 external_user_id_taken. Too many requests in a minute are answered 429 rate_limited with Retry-After.

Example: Acme HR

Acme HR runs LinkedIn tasks for Priya (in India) and Rahul (in the US), with an API key in its shared project "Acme HR".

1. One identity each: identities create with external_user_id, a label and country in or us.
2. A login link each for linkedin.com, shown in Acme's own app; Priya and Rahul sign in there.
3. Tasks by identity: browser_task with Priya's identity runs on her LinkedIn session, from an Indian IP on her own device; Rahul's runs from the US on his.
4. Each result ends with its cost and identity; at month end Acme reads each user's usage and bills them.
5. Priya leaves: identities delete wipes her login, session and device. Her past costs stay.