Opsis API / v1

Retrieve searches

Read results and progress, or list your recent searches.

Retrieve status and results

GET/v1/searches/{run_id}

Fetch an owned run’s current snapshot. Results accumulate while modules finish. Polling and reading results do not spend additional search credits.

shell

curl https://api.useopsis.com/v1/searches/00000000-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $OPSIS_API_KEY"

Illustrative running snapshot · fields abbreviated

{
  "run_id": "00000000-0000-4000-8000-000000000001",
  "status": "running",
  "type": "email",
  "query": "[email protected]",
  "total_results": 1,
  "results": [
    {
      "id": 1,
      "type": "account",
      "entity_type": "account",
      "platform": "Example platform",
      "value": "jasondraper01",
      "confidence": 1,
      "source": "example_module",
      "metadata": {
        "username": "jasondraper01",
        "name": "Jason Draper",
        "profile_url": "https://example.com/jasondraper01"
      },
      "created_at": "2026-10-01T12:00:00Z"
    }
  ],
  "progress": {
    "modules_total": 100,
    "modules_completed": 75,
    "modules_succeeded": 73,
    "modules_failed": 2,
    "modules_pending": 25,
    "coverage": "pending"
  },
  "coverage": "pending",
  "results_available": true
}

completed and failed are terminal. Completion can include partial coverage; check the coverage fields.

List recent searches

GET/v1/searches?limit=20

Returns your recent runs, newest first. limit defaults to 20 and is clamped to 1–100. Each list item contains metadata, not its results.

Example response

{
  "total": 1,
  "searches": [
    {
      "run_id": "00000000-0000-4000-8000-000000000001",
      "type": "email",
      "query": "[email protected]",
      "status": "completed",
      "created_at": "2026-10-01T12:00:00Z"
    }
  ]
}

Use each item’s run_id with the snapshot endpoint to fetch its results. total is the number of entries in this response, not an all-time count.