Get started

Quickstart

Start a search, then read its results as they arrive.

Get your API key

Your key is in your Predicta Search account settings, in the API tab (sign in first). Keep it on your server (why).

Start the search

Send the query. The answer comes back at once, with the search_id to follow.

curl -X POST https://dev.predictasearch.com/api/v2/search \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "johndoe", "query_type": "username", "networks": ["all"]}'

import httpx

r = httpx.post(
    "https://dev.predictasearch.com/api/v2/search",
    headers={"x-api-key": API_KEY},
    json={"query": "johndoe", "query_type": "username", "networks": ["all"]},
)
search_id = r.json()["search_id"]

const res = await fetch("https://dev.predictasearch.com/api/v2/search", {
  method: "POST",
  headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ query: "johndoe", query_type: "username", networks: ["all"] }),
});
const { search_id } = await res.json();

202Accepted

{
  "search_id": "3911861a-685d-420f-aae2-0bb2dba36ead",
  "status": "running",
  "total": 1840,
  "networks_rejected": []
}

Read the results as they arrive

Open the stream of that search_id. The connection stays open and events arrive one by one.

curl -N https://dev.predictasearch.com/api/v2/search/$SEARCH_ID \
  -H "x-api-key: $API_KEY" \
  -H "Accept: text/event-stream"

with httpx.stream(
    "GET",
    f"https://dev.predictasearch.com/api/v2/search/{search_id}",
    headers={"x-api-key": API_KEY, "Accept": "text/event-stream"},
    timeout=httpx.Timeout(30, read=60),
) as stream:
    for line in stream.iter_lines():
        print(line)

const stream = await fetch(`https://dev.predictasearch.com/api/v2/search/${search_id}`, {
  headers: { "x-api-key": API_KEY, Accept: "text/event-stream" },
});
const decoder = new TextDecoder();
for await (const chunk of stream.body) {
  process.stdout.write(decoder.decode(chunk, { stream: true }));
}

text/event-stream

id: 0
event: result
data: {"network":"github","data":[{"username":"johndoe","platform":"github","link":"https://github.com/johndoe"}]}

id: 1
event: source_error
data: {"network":"hudsonrock","reason":"timeout"}

id: 2
event: progress
data: {"done":94,"total":1840,"found":68,"failed":4}

…

id: 615
event: done
data: {"found":379,"failed":113,"credit_debited":true,"credit_balance":974}

Stop on the last event

done means the search is complete. failed means it was interrupted and its credit refunded. Either one closes the stream.

A production client also resumes the stream when the connection drops. Full client examples do it in Python and JavaScript.