Status of a search: CasePrimus.ai API

Overview

Status and counters. status is ACTIVE (more may exist), COMPLETE (every source read to its end or to the results-per-search cap) or EXPIRED (the results have been deleted; only the counts remain). An asynchronous search (mode: ASYNC) is RUNNING while it collects, then COMPLETE or FAILED; collected is how many results are stored so far (final once COMPLETE) and a FAILED search carries a failureReason. Does not contact a data source. Requires historicalSearch.read.

Auth API key

Send your API key in the X-CasePrimus-Api-Key header. See Authentication for how to create a key, and Rate limits & errors for how requests are counted.

Parameters

Name	In	Description
`searchId` string Required	path	The id returned when the resource was created.

Example request

Replace CASEPRIMUS_API_KEY with your key.

Request

BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl "$BASE/historical-search/SEARCH_ID" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"

const BASE = "https://api.caseprimus.ai/api/caseprimus/v1";

const res = await fetch(BASE + "/historical-search/SEARCH_ID", {
  method: "GET",
  headers: {
    "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY,
  },
});

const data = await res.json();

import os
import requests

BASE = "https://api.caseprimus.ai/api/caseprimus/v1"

res = requests.request(
    "GET",
    BASE + "/historical-search/SEARCH_ID",
    headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]},
)

data = res.json()

Responses

200The search.

Field	Description
`searchId` string
`mode` enum	ASYNC: collected in the background (see POST /historical-search). `SYNCASYNC`
`status` enum	SYNC searches are ACTIVE, COMPLETE or EXPIRED. ASYNC searches are RUNNING, COMPLETE, FAILED or EXPIRED. `ACTIVECOMPLETEEXPIREDRUNNINGFAILED`
`name` string
`partyType` enum	`PETITIONERRESPONDENTBOTH`
`filters` object
`clientReference` string or null
`delivered` integer	Results delivered so far. For a COMPLETE asynchronous search: all of them (reading its pages is free and repeatable).
`collected` integer	ASYNC only. Results stored so far; final once COMPLETE.
`completedAt` integer or null	ASYNC only. Epoch ms the search finished (COMPLETE or FAILED); null while RUNNING.
`failureReason` string	ASYNC only, present when FAILED: why, in words for a person. Nothing was charged.
`warnings` array of object
`code` enum	`RESULT_CAP_REACHEDSOURCE_UNAVAILABLE`
`message` string
`createdAt` integer	Epoch ms.
`expiresAt` integer	Epoch ms. Results are deleted at this time.

Response 200

{
  "searchId": "CPHS0exampledemo0001",
  "mode": "SYNC",
  "status": "ACTIVE",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 100,
  "warnings": [],
  "createdAt": 1791600000000,
  "expiresAt": 1792204800000
}

{
  "searchId": "CPHS0exampledemo0001",
  "mode": "SYNC",
  "status": "COMPLETE",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 137,
  "warnings": [],
  "createdAt": 1791600000000,
  "expiresAt": 1792204800000
}

{
  "searchId": "CPHS0exampleasync01",
  "mode": "ASYNC",
  "status": "RUNNING",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 0,
  "warnings": [],
  "createdAt": 1791936000000,
  "expiresAt": 1792566000000,
  "collected": 1240,
  "completedAt": null
}

{
  "searchId": "CPHS0exampleasync01",
  "mode": "ASYNC",
  "status": "COMPLETE",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 1843,
  "warnings": [],
  "createdAt": 1791936000000,
  "expiresAt": 1792544400000,
  "collected": 1843,
  "completedAt": 1791939600000
}

{
  "searchId": "CPHS0exampleasync01",
  "mode": "ASYNC",
  "status": "FAILED",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 0,
  "warnings": [],
  "createdAt": 1791936000000,
  "expiresAt": 1792026000000,
  "collected": 0,
  "completedAt": 1791939600000,
  "failureReason": "A data source was unavailable for too long. Nothing was charged - please start the search again later."
}

{
  "searchId": "CPHS0exampledemo0001",
  "mode": "SYNC",
  "status": "EXPIRED",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 137,
  "warnings": [],
  "createdAt": 1790908800000,
  "expiresAt": 1791513600000
}

404Unknown or deleted search.

Response 404

{
  "httpStatusCode": 404,
  "code": 61449,
  "message": "This search was not found",
  "appError": true
}

Error responses share one shape, listed on Rate limits & errors.

Status of a search

Overview

Parameters

Example request

Responses

Related