Skip to content
Listrar Product Data Gateway

Get this tenant's usage

GET
/v1/usage
curl --request GET \
  --url https://api.listrar.com/v1/usage \
  --header 'Authorization: Bearer <token>'

The tenant’s own metered events. Cross-tenant reads are structurally impossible here — row-level security enforces it, this handler adds no filter of its own.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

Recent usage events for the calling tenant.

Media typeapplication/json
Response envelope
object
request_id
required
string
/^req_[0-9A-HJKMNP-TV-Z]{26}$/
status
required

Typed result status. Absence (‘not_found’, ‘unknown’) is an answer carried at HTTP 200, never a 404 — see ERROR_MODEL.md design rule 1. ‘not_found’ MUST NOT be softened (06 §9).

Allowed values: found not_found unknown ambiguous partial
reason

REQUIRED when status = ‘unknown’.

Allowed values: NO_SOURCE SOURCE_UNAVAILABLE OUT_OF_SCOPE LICENCE_RESTRICTED TIMEOUT AMBIGUOUS_INPUT
data
object | null
claims
Array<object>
Claim
object
id
required
string
subject
required
string
predicate
required
string
object
required
object
value
required
unit
string | null
language
string | null
claim_type
required

INFERENCE and ESTIMATION can never be promoted to FACT. See 10 §3.

Allowed values: FACT SOURCE ASSERTION VALIDATION INFERENCE ESTIMATION UNKNOWN
method

REQUIRED for INFERENCE and ESTIMATION

string | null
method_version
string | null
source_ref
string | null
publisher_ref
string | null
evidence_refs
Array<string>
0
verification_status
Allowed values: unverified domain_verified registry_verified contract_verified disputed
verification_method
string | null
trust_level
required
Allowed values: L0 L1 L2 L3 L4 L5
confidence
number
<= 1
published_at
string | null format: date-time
retrieved_at
required
string format: date-time
superseded_by
string | null
sources
Array<object>
object
id
required
string format: uuid
kind
required
Allowed values: registry gs1_resolver publisher_endpoint partner_feed tenant_upload web
origin
required
string
operator_party_id
string | null format: uuid
trust_tier
required
integer
<= 4
robots_policy
string | null
enabled
boolean
licence_name
required
string
may_store_raw
boolean
may_redistribute_verbatim
boolean
may_redistribute_derived
boolean
attribution_required
string | null
licence_determined_by
string
licence_determined_at
string format: date-time
licence_review_due_at
string format: date-time
meta
required
object
duration_ms
required
integer
coverage

What was actually consulted, so a caller can distinguish ‘does not exist’ from ‘not covered’. Present on absence and on batch responses.

object
sources_consulted
required
Array<string>
sources_skipped
Array<object>
object
id
required
string
reason
required
Allowed values: LICENCE_RESTRICTED CIRCUIT_OPEN OUT_OF_SCOPE TIMEOUT DISABLED
next_cursor

Opaque cursor for the next page; absent means end of results. Cursor pagination only, never offset.

string
validation

Up to four independent axes, never collapsed into one verdict (12 §5). A class is absent when no rule of that class has been evaluated for this subject — which is not the same as ‘not_assessed’, a recorded verdict.

object
technical
Allowed values: pass fail warn not_assessed
business
Allowed values: pass fail warn not_assessed
regulatory
Allowed values: pass fail warn not_assessed
authority
Allowed values: none attested
warnings
Array<object>
object
code
required
string
severity
required
Allowed values: info warn error
detail
string
errors
Array<object>
Problem (RFC 9457 + extensions)
object
type
required
string format: uri
title
required
string
status
required
integer
>= 100 <= 599
code
required
string
/^[A-Z][A-Z0-9_]+$/
detail
string
<= 512 characters
request_id
string
retryable
required
boolean
docs_url
string format: uri
Example
{
  "status": "found",
  "reason": "NO_SOURCE",
  "claims": [
    {
      "subject": "gtin14:04012345678901",
      "predicate": "dpp:carbonFootprintKgCO2e",
      "claim_type": "FACT",
      "verification_status": "unverified",
      "trust_level": "L0"
    }
  ],
  "sources": [
    {
      "kind": "registry"
    }
  ],
  "meta": {
    "coverage": {
      "sources_skipped": [
        {
          "reason": "LICENCE_RESTRICTED"
        }
      ]
    }
  },
  "validation": {
    "technical": "pass",
    "business": "pass",
    "regulatory": "pass",
    "authority": "none"
  },
  "warnings": [
    {
      "severity": "info"
    }
  ]
}

Headers

Section titled “Headers”
x-request-id
string

Echoes the envelope’s request_id.

401

Section titled “401”

UNAUTHENTICATED

Media typeapplication/problem+json
Problem (RFC 9457 + extensions)
object
type
required
string format: uri
title
required
string
status
required
integer
>= 100 <= 599
code
required
string
/^[A-Z][A-Z0-9_]+$/
detail
string
<= 512 characters
request_id
string
retryable
required
boolean
docs_url
string format: uri
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

500

Section titled “500”

INTERNAL_ERROR

Media typeapplication/problem+json
Problem (RFC 9457 + extensions)
object
type
required
string format: uri
title
required
string
status
required
integer
>= 100 <= 599
code
required
string
/^[A-Z][A-Z0-9_]+$/
detail
string
<= 512 characters
request_id
string
retryable
required
boolean
docs_url
string format: uri
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}