API Reference

Build with the TraceFind OSINT platform.

Programmatic access to the TraceFind investigation engine. Search emails, usernames, and phone numbers across hundreds of sources. Stream results in real time, generate reports, and manage credits — all from a single, consistent API surface.

Base URL https://tracefind.info
Protocol HTTPS · JSON · SSE
Authentication Bearer Token
Cost per search 5 credits
01 — Getting Started

Overview

The TraceFind API is a JSON-over-HTTPS service. Most endpoints are protected by a Bearer token tied to a user account; the email reconnaissance endpoint streams results over Server-Sent Events. Costly searches consume credits — typically 5 credits per query, automatically refunded if no findings are returned.

Base URL
https://tracefind.info
Default content type
application/json
01 — Getting Started

Authentication

Most endpoints expect a Bearer token in the Authorization header. The token is your user_id, returned by /signup. Errors return standard HTTP status codes with a JSON { "detail": "..." } body.

Header
HTTP
Authorization: Bearer YOUR_TOKEN
Note
Credit policy. Each authenticated search costs 5 credits. If a search returns no findings, credits are refunded automatically. Insufficient balance returns 400 Too low on credits.
02 — Account

Account

Create accounts, sign in with an existing account number, and check the remaining credit balance.

POST /signup Public

Provisions a new user account. Returns a 12-character user_id that doubles as your authentication token. Store it safely — there is no password recovery.

Request
cURL
curl -X POST https://tracefind.info/signup
200 OK
JSON
{ "msg": "Success", "user_id": "YOUR_TOKEN" }
POST /login Public

Verifies an existing account by its account_number (the user_id returned from signup). Returns the same id on success.

Body
FieldTypeDescription
account_number* string The user's existing 12-character account ID.
Request
cURL
curl -X POST https://tracefind.info/login \ -H "Content-Type: application/json" \ -d '{"account_number": "YOUR_TOKEN"}'
200 OK
JSON
{ "msg": "Success", "user_id": "YOUR_TOKEN" }
400 Error
JSON
{ "detail": { "msg": "Error", "description": "Couldn't find ID." } }
POST /credit_amount Public

Returns the current credit balance for a given user.

Body
FieldTypeDescription
user_id* string The user account ID.
Request
cURL
curl -X POST https://tracefind.info/credit_amount \ -H "Content-Type: application/json" \ -d '{"user_id": "YOUR_TOKEN"}'
200 OK
JSON
{ "amount": 250 }
03 — Search

Search

The investigative core of the API. Email searches stream live as services are queried; username and phone searches return their full result set in one response. Each search costs 5 credits.

GET /stream/{email} Auth required

Streams an OSINT search across hundreds of services for the given email address using Server-Sent Events. Each event is a JSON payload describing one finding (social account, leak, Google profile data, etc.). The stream terminates with a literal [STOP] marker and a final report_id used to retrieve the PDF later.

Auth note. Because EventSource can't set headers, this endpoint accepts the auth token via the auth_token query parameter instead of a Bearer header.
Path
FieldTypeDescription
email* string Target email address (URL-encoded).
Query
FieldTypeDescription
auth_token* string Your user_id used as the authentication token.
Request
JavaScript
const es = new EventSource( "https://tracefind.info/stream/target@example.com?auth_token=YOUR_TOKEN" ); es.onmessage = (e) => { if (e.data === "[STOP]") return es.close(); const payload = JSON.parse(e.data); // handle finding… };
Stream events
SSE payload stream
// Domain validation (first event) {"type": "domain_validation", "domain_valid": true} // Breach / leak findings {"type": "leaks", "data": [/* breach records */]} // One event per matched social service { "type": "social", "name": "github", "url": "https://github.com", "others": { /* service-specific data */ } } // Optional Google account details {"type": "google", "data": { /* … */ }} // Final report identifier — save it for PDF retrieval {"type": "report_id", "data": "K9X2L4M7P3R8"} // Stream end marker [STOP]
POST /username_info Auth required

Searches for a username across hundreds of platforms. Returns matched profiles in a single JSON response.

Body
FieldTypeDescription
username* string Target username to investigate.
Request
cURL
curl -X POST https://tracefind.info/username_info \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"username": "johndoe"}'
200 OK
JSON
{ "message": "Success", "for": "johndoe", "data": [ { "site": "github", "url": "https://github.com/johndoe", "exists": true } ], "phones": [], "emails": [], "github": [], "leaks": [] }
Errors
401   missing or invalid auth token
400   credit balance below 5, or username missing
POST /phone_info Auth required

Investigates a phone number across messengers, public directories, and known data sources.

Body
FieldTypeDescription
phone* string Target phone number, ideally in E.164 format (e.g. +491701234567).
Request
cURL
curl -X POST https://tracefind.info/phone_info \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"phone": "+491701234567"}'
200 OK
JSON
{ "message": "Success", "for": "+491701234567", "data": [ { "service": "whatsapp", "registered": true } ] }
04 — History & Reports

History & Reports

Retrieve past searches, delete entries, and export findings as PDF reports.

GET /history Auth required

Returns the full list of historical searches for the authenticated user.

Request
cURL
curl https://tracefind.info/history \ -H "Authorization: Bearer YOUR_TOKEN"
200 OK
JSON
{ "message": "Success", "history": [ { "timestamp": "2026-04-30T18:14:22Z", "search_type": "email", "search_term": "target@example.com", "report_id": "K9X2L4M7P3R8", "results": [/* full event log */] } ] }
DELETE /history/{report_id} Auth required

Permanently removes a single history entry. This action cannot be undone.

Path
FieldTypeDescription
report_id* string The 12-character report identifier returned by a search.
Request
cURL
curl -X DELETE https://tracefind.info/history/K9X2L4M7P3R8 \ -H "Authorization: Bearer YOUR_TOKEN"
200 OK
JSON
{ "message": "Success", "report_id": "K9X2L4M7P3R8" }
POST /get_pdf_report Auth required

Generates and returns a formatted PDF report for a previous email search. The response is the binary file (application/pdf).

Body
FieldTypeDescription
report_id* string Identifier of the report to render.
Request
cURL
curl -X POST https://tracefind.info/get_pdf_report \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"report_id": "K9X2L4M7P3R8"}' \ --output report.pdf
200 OK
Binary PDF file. Content-Type: application/pdf, with Content-Disposition: attachment; filename="report.pdf".