Stored analyses

Every call to POST /v1/analyze or POST /v1/classify creates an analysis with an an_… id. Unless you sent keep_results: false, its results are stored and you can read them with these endpoints.

Storing results does not mean storing the file: that is decided by storage. See Storage and privacy.

Retrieve an analysisCopy Anchor Link

GET /v1/analyses/{id}

Returns the analysis (or classification) object with its current status and the still-valid signed URLs in exports. It works with keys of either mode, as long as the analysis belongs to your account.

It returns 404 resource_missing if the analysis does not exist, belongs to another account, was deleted or was created with keep_results: false.

This is how you poll an asynchronous analysis if you do not use webhooks. Poll with increasing waits and stop when status is completed or failed. Webhooks are better: they do not use up your rate limit.

curl https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

List analysesCopy Anchor Link

GET /v1/analyses

The list only includes analyses of your key's mode (test or live), newest first. It does not include deleted analyses or those created with keep_results: false.

{
  "object": "list",
  "data": [
    { "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "object": "analysis", "status": "completed", "…": "…" }
  ],
  "has_more": true,
  "url": "/v1/analyses"
}

PaginationCopy Anchor Link

Pagination is cursor based: while has_more is true, request the next page passing the id of the last item as starting_after. There is no next_cursor field. More in Pagination.

#!/usr/bin/env bash
set -euo pipefail

after=""
while :; do
  page=$(curl -sf -G https://api.constaia.com/v1/analyses \
    -H "Authorization: Bearer $CONSTAIA_API_KEY" \
    --data-urlencode "limit=100" \
    --data-urlencode "status=completed" \
    --data-urlencode "metadata[event]=42" \
    ${after:+--data-urlencode "starting_after=$after"})
  echo "$page" | jq -r '.data[] | [.id, .document.type, .verdict.status] | @tsv'
  [ "$(echo "$page" | jq -r .has_more)" = "true" ] || break
  after=$(echo "$page" | jq -r '.data[-1].id')
done

Delete an analysisCopy Anchor Link

DELETE /v1/analyses/{id}

Deletes the file (if it was stored), the extracted results and the exports. It cannot be undone. Afterwards, GET returns 404. Billing metadata (pages, credits, type) is kept for your usage records.

curl -X DELETE https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

{ "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "object": "analysis", "deleted": true }

In the SDKs: await constaia.analyses.delete(id) (JavaScript) and $constaia->analyses->delete($id) (PHP). If you just never want the file stored, use storage: "none" and keep_results: false when analysing; see Analyse without storing anything.

Export an analysisCopy Anchor Link

GET /v1/analyses/{id}/export?format=json|csv|xlsx|xml|vcard|pdf

Generates the file on the fly (default json) and returns it as a download with Content-Disposition: attachment; filename="an_….xlsx". It does not expire like the exports URLs: you can request it as long as the analysis exists. If the analysis has not finished yet, it answers 409 analysis_not_completed. Formats in Exports.

curl -o analysis.xlsx \
  "https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2/export?format=xlsx" \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Signed downloads (/v1/files)Copy Anchor Link

When you analyse with export, the exports field carries URLs like this one:

https://api.constaia.com/v1/files/exp_01J9Z8Q3K4M5N6P7Q8R9S0T1V2?expires=1790157602&sig=…

• They need no key: the sig signature authorises the download. Treat them as a temporary secret and do not publish them.
• They expire after 24 hours. After that they return 404. GET /v1/analyses/{id} only includes the ones still valid in exports; if you need the file later, use GET /v1/analyses/{id}/export.
• They are always served from api.constaia.com, never from a storage URL.
• If you change expires or sig, the signature stops being valid and the response is 404.

Next stepsCopy Anchor Link