Data Management

Risicare provides a data deletion API for GDPR Article 17 (Right to Erasure) compliance. Use it to delete all traces and sessions associated with a data subject.

Delete by Subject

POST /v1/data/delete-by-subject
Content-Type: application/json
Authorization: Bearer rsk-...
 
{
  "session_id": "user-session-abc",
  "agent_id": "support-agent",
  "trace_ids": ["trace-id-1", "trace-id-2"]
}

Provide at least one identifier. All matching spans and sessions are deleted, scoped to your project.

Requires the admin role — a viewer-role key receives 403.

Response

The response is polymorphic. You get 200 when the erasure finished inside the request budget, and 202 when it did not — a large subject will routinely return 202.

200 — finished:

{
  "spans_deleted": 42,
  "sessions_deleted": 1,
  "traces_affected": 3,
  "redis_entries_purged": 0,
  "warnings": [],
  "complete": true,
  "erasure_job_id": "6f1c…",
  "stores_outstanding": []
}

202 — accepted, still running. A Location header points at GET /v1/data/erasure-jobs/{job_id}, which you poll until it reaches a terminal state:

{
  "job_id": "6f1c…",
  "erasure_job_id": "6f1c…",
  "location": "/v1/data/erasure-jobs/6f1c…",
  "status": "running",
  "stores_outstanding": ["spans", "sessions"]
}

warnings lists any store that could not be erased, and complete is false whenever warnings is non-empty. stores_outstanding names the stores that have not been erased yet.

Example: Delete a User's Session

curl -X POST https://app.risicare.ai/api/v1/data/delete-by-subject \
  -H "Authorization: Bearer rsk-..." \
  -H "Content-Type: application/json" \
  -d '{"session_id": "user-123-session"}'

Example: Delete Specific Traces

Branch on the status code — do not assume 200:

import time
 
import httpx
 
BASE = "https://app.risicare.ai"
headers = {"Authorization": "Bearer rsk-..."}
 
resp = httpx.post(
    f"{BASE}/api/v1/data/delete-by-subject",
    headers=headers,
    json={"trace_ids": ["abc123", "def456"]},
)
 
PENDING = {"pending", "running"}          # job is still owed an outcome
# Terminal states are "succeeded", "partial", "failed".
# Only "succeeded" claims a complete erasure.
 
if resp.status_code == 200:
    body = resp.json()
    print("erased:", body["spans_deleted"], "spans; complete:", body["complete"])
elif resp.status_code == 202:
    # Not finished in-request. Follow the Location header the server handed
    # back rather than building the URL yourself.
    status_url = resp.headers.get("Location") or resp.json()["location"]
    while True:
        job = httpx.get(f"{BASE}{status_url}", headers=headers).json()
        if job["status"] not in PENDING:
            break
        time.sleep(2)
 
    if job["status"] == "succeeded":
        print("erasure complete")
    else:
        # "partial" or "failed" — the subject's data is NOT fully erased.
        print(job["status"], "- outstanding:", job.get("stores_outstanding"))
else:
    resp.raise_for_status()

When Is the Data Actually Gone?

What this means in practice:

• On 200, the counts are accurate and the covered rows are physically removed — ClickHouse deletes run with mutations_sync=1, so they are not queued behind a background merge
• On 202, only the stages already reported done have run; stores_outstanding names the rest
• Re-issuing the identical request adopts the same subject's unfinished job rather than starting a new one, so retries are safe
• A span the ingestion worker has already read into its in-memory batch is purged within roughly one flush interval rather than instantly
• If any store could not be erased, it is named in warnings and complete is set to false
• For compliance purposes, an erasure is effective when it reports 200 with complete: true, or when its job reaches succeeded. A 202, a partial, or complete: false means the erasure is not yet finished

Error Handling

If the deletion fails (e.g., database unreachable), the API returns 500 with an error message. A 200 means the erasure finished in-request — not that it was queued. A 202 means it is still running and you must poll the job.

{
  "detail": "Data deletion failed. Please retry. If this persists, contact support."
}

What Gets Deleted

All deletions are scoped to your project — you can only delete data that belongs to the API key's project.

Automatic Data Retention

In addition to on-demand deletion, Risicare automatically purges aged data with fixed ClickHouse TTLs, applied uniformly to every project regardless of plan. Retention is not a single window — it varies by data type:

One more thing that is easy to miss: evaluations and scorer results are kept for a full year, four times longer than the traces they were computed over; if the scored content is sensitive, that is the window that governs.