> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osint.ly/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Create a search, stream progress, and fetch final results in minutes.

This guide walks through the minimal API flow using cURL.

<Note>
  You need a valid bearer token first. See [Authentication](/api-reference/authentification).
</Note>

## 1) Check service health

```bash theme={null}
curl -X GET "https://api.osint.ly/health"
```

## 2) Validate your token

```bash theme={null}
curl -X GET "https://api.osint.ly" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

## 2.1) Optional: test Radar (free plan)

Radar access is free, but still requires an authenticated API key.

```bash theme={null}
curl -X GET "https://api.osint.ly/radar/breaches?limit=2&sortBy=recently-added" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

## 3) Create a search

```bash theme={null}
curl -X POST "https://api.osint.ly/search" \
  -H "Authorization: Bearer $OSINTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "type": "Email Address",
      "value": "target@example.com"
    },
    "features": {
      "breached_accounts": true,
      "registered_accounts": "include"
    },
    "cache": {
      "mode": "prefer"
    }
  }'
```

Save the returned `search.id` for the next calls.

### Optional: run selected modules only

```bash theme={null}
curl -X POST "https://api.osint.ly/search" \
  -H "Authorization: Bearer $OSINTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "type": "Email Address",
      "value": "target@example.com"
    },
    "modules": {
      "mode": "selected",
      "ids": [
        "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
        "95c36c17-f76e-4911-bd4e-8ea57515b2fb"
      ]
    }
  }'
```

If `modules` is omitted, Osintly uses the default module set for the selected search type.

## 4) Stream progress (SSE)

```bash theme={null}
curl -N -X GET "https://api.osint.ly/search/SEARCH_ID/stream" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

You receive incremental events while the search is running.

Concrete output example:

```text theme={null}
event: connected
data: {"search_id":"SEARCH_ID","timestamp":"2026-06-23T14:10:01.000Z"}

event: module.result
data: {"search_id":"SEARCH_ID","module":{"id":"github","name":"GitHub"},"card":{"github_001":{"username":"target"}},"timestamp":"2026-06-23T14:10:03.000Z"}

event: search.finished
data: {"search_id":"SEARCH_ID","status":"completed","totals":{"module_results":1},"timestamp":"2026-06-23T14:10:09.000Z"}
```

Concrete BYOK stream output example:

```text theme={null}
event: byok.result
data: {"search_id":"SEARCH_ID","provider":"osint_industries","card":{"source":"github","username":"target"},"timestamp":"2026-06-23T14:11:03.000Z"}

event: byok.finished
data: {"search_id":"SEARCH_ID","provider":"osint_industries","status":"success","resultCount":6,"timestamp":"2026-06-23T14:11:08.000Z"}
```

If modules are sharded across runners, you can also receive `search.progress` messages such as:

```text theme={null}
event: search.progress
data: {"search_id":"SEARCH_ID","status":"running","message":"shard 1/3 progress 5/12","result_cards_count":17,"timestamp":"2026-06-23T14:11:04.000Z"}
```

## 5) Fetch search state

```bash theme={null}
curl -X GET "https://api.osint.ly/search/SEARCH_ID" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

## 6) Fetch final structured results

```bash theme={null}
curl -X GET "https://api.osint.ly/search/SEARCH_ID/results" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

## 7) Fetch leak source payloads

```bash theme={null}
# List available leak sources for a search
curl -X GET "https://api.osint.ly/search/SEARCH_ID/results/leaks" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"

# Fetch one source (optional page)
curl -X GET "https://api.osint.ly/search/SEARCH_ID/results/leaks/snusbase?page=1" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

## 8) Optional: receive results by webhook

Provide `delivery.webhook.url` (and optionally `delivery.webhook.secret`) when creating the search:

```json theme={null}
{
  "query": {
    "type": "Email Address",
    "value": "target@example.com"
  },
  "delivery": {
    "webhook": {
      "url": "https://client.example/webhooks/osintly",
      "secret": "super-secret-webhook-key"
    }
  }
}
```

When the search completes, your endpoint receives a JSON payload with:

* `searchId`
* `status` (`finished` or `error`)
* `finishedAt`
* `search` metadata (`id`, `value`, `type`, `options`, `created_at`)
* `summary` counts
* `links` to retrieve state, results, BYOK details, and leaks

The webhook is a lightweight completion notification. Use the returned links to fetch the full normalized payloads from the API.

Full payload details: [Webhooks](/api-reference/webhooks)

## 9) Recommended: clean up completed searches

After you have fetched and stored the data you need, delete completed searches you no longer need:

```bash theme={null}
curl -X POST "https://api.osint.ly/search/delete" \
  -H "Authorization: Bearer $OSINTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["SEARCH_ID"]
  }'
```

Use this only after the search is terminal. Deletion requests are all-or-nothing and support up to `100` IDs per call.

Cleanup guidance: [Search Retention](/api-reference/search-retention)

***

## Rate limits and usage

Use `GET /usage` to read current global and daily usage windows.

```bash theme={null}
curl -X GET "https://api.osint.ly/usage" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

<Tip>
  If you receive `429`, respect `Retry-After` and `X-RateLimit-Reset` headers before retrying.
</Tip>

## Terms and ethics

* Terms of Use: [https://osint.ly/terms](https://osint.ly/terms)
* Ethics Policy: [https://osint.ly/ethics](https://osint.ly/ethics)

## Next steps

* Explore the OpenAPI endpoint docs in the **Endpoints** group
* Read [Domains](/api-reference/domains) for type values and request patterns