Skip to main content
This page documents how Osintly API plans work, how they differ from Osintly app plans, how API access follows the active workspace, and how runtime capacity is enforced.

​
Plan model

  • Osintly API plans and Osintly app plans are separate.
  • You can have:
    • both plans
    • API plan only
    • app plan only
    • neither
  • If you have an API plan without an Osintly app plan, you get API access only.
  • An organization can hold its own API plan. It remains separate from the organization app plan and from each member’s personal API plan.

​
API workspace scope

Open https://osint.ly/workspace/api after selecting the workspace you want to manage. Within an organization, owners and admins can create, revoke, and manage API keys. All members can view API keys and usage. Only the owner can manage organization API billing and invoices. An organization API key belongs to the organization, not to the member who created it. Switching workspaces does not move keys, usage, subscriptions, or invoices.

​
API workspace console

The selected workspace’s API console has Access, Keys, Usage, and Docs views. When billing access is available, it also shows Billing and Invoices. Keys can be created or revoked within the current plan’s key limit; the Usage view shows daily and monthly consumption and any active API add-ons. Billing lists the API plan and add-ons as separate items, while Invoices shows their billing documents. Available tabs and actions depend on the selected workspace, subscription, and role. API add-ons can extend the API capacity shown in the console. Review the add-on’s included units, request rate, concurrency, status, and billing terms before purchase. Add-on usage and subscription management are separate from app search credits; changing a Personal app plan does not change API capacity. Dates and clock times displayed in the Osintly API console are in UTC.

​
Buying API access

From the API pricing page, choose a plan and enter the API checkout. If you belong to one or more organizations, checkout asks whether to bill Personal or a selected organization before payment. Authentication and MFA may be required first. The account or organization chosen at checkout owns the resulting API subscription and keys. API add-ons are managed in the same workspace’s API console after activation. Verify the target workspace before confirming a purchase.

​
Free API plan

  • The Free API plan can evolve over time.
  • Current behavior: free API key access plus unlimited Radar API access.
  • Radar endpoints still require authentication with an API key.
  • The website’s limited free search previews are a separate feature. They do not grant POST /search access on the Free API plan.

​
How to claim Free API plan

Free API plan is not automatically active on every account. To activate it:
  1. Open https://osint.ly/workspace/api
  2. Accept Terms and Ethics
  3. Claim the Free API plan
  4. Create your API key

​
Plan lifecycle behavior

​
Canceling a paid API plan

When a paid API plan is canceled, subscription access switches back to Free API automatically.

​
Downgrade with lower API key quota

If you downgrade to a plan with a lower API key limit:
  • extra keys are marked as revoked
  • extra keys are not deleted
  • to create new keys or un-revoke old keys, you must be compliant with the new key limit

​
Billing separation

For an organization, API billing remains separate from the organization app subscription and is managed by the organization owner in the active organization workspace.

​
Capacity and limits

Search endpoints enforce plan-based runtime limits.
  • Requests per minute can return:
    • 429 RATE_LIMIT_RPM_EXCEEDED
  • Global/day usage windows can return:
    • 429 RATE_LIMIT_EXCEEDED
  • Concurrency cap can return:
    • 409 MAX_CONCURRENCY_EXCEEDED
Use GET /usage to inspect current limits and remaining allowance.

​
Concurrency and sharding behavior

  • Search orchestration can split modules into shards.
  • Current max shard count is 3.
  • When runner capacity is saturated, stream emits search.progress events with wait messages.
  • When capacity returns, progress events continue with shard progression messages (for example shard 2/3 progress 9/12).
See SSE Reference for concrete stream examples.

​
Processing timeout (stuck searches)

If a search remains in queued or running and exceeds the orchestration TTL, it is failed automatically.
  • Default TTL: 3,600,000 ms (1 hour)
  • After TTL, the run is marked failed and cleaned up by the orchestrator
  • TTL can be overridden by environment configuration
If a search appears stuck, use:
  1. GET /search/{id} for current status
  2. GET /search/{id}/stream to inspect progress events
  3. GET /search/{id}/results once terminal
Using the API implies responsible and compliant usage.