Timeline | API Reference Guide | CourtMesh
    Skip to main content
    On this page

    Timeline

    Request a case's order timeline, stored or live, and poll the job for the result.

    Timeline endpoints
    A two step job: request the timeline, then fetch the result.
    POST

    /request-timeline

    1 credit stored read, 20 credits when refresh triggers a live fetch

    By default this reads whatever orders CourtMesh already has stored for the case, priced at 1 credit, and the response says so with meta.liveFetch: false. Send refresh: true to actually ask the source court portal for current orders; that only costs the full 20 credits when it genuinely triggers live upstream work (meta.liveFetch: true), never for a stored read that happened to satisfy the request anyway. High Court and District Court cases can be live-fetched this way; tribunal cases cannot, and a refresh request against one falls back to the stored read with liveFetchSupported: false rather than erroring.

    Refresh gates, in order

    • Tier access. Free has no live fetch access at all (TIER_LIMITS.free.liveFetchAllowed is false): refresh: true on Free is refused with HTTP 403 LIVE_FETCH_NOT_ALLOWED before any work or charge. A plain stored read (refresh omitted or false) still works on Free.
    • Its own per minute ceiling. A refresh call is tighter than your account's general rate limit, since it can trigger real work against a court portal rather than a stored lookup.
    • A daily live-fetch cap per tier. Once exhausted for your account's day, further refresh calls are refused with HTTP 429 LIVE_FETCH_LIMIT_REACHED and a Retry-After header; a plain stored read is unaffected.
    • A once-per-case-per-day gate at the source. Independent of the caps above, Supreme Court and District Court live fetches are each deduplicated to at most once per calendar day per case, so asking twice in one day for the same case returns the same stored result rather than hitting the portal again.

    Request body

    FieldTypeRequiredNotes
    case_idstringYesThe case identifier to fetch orders for. Note the snake_case name: this endpoint predates the camelCase convention used elsewhere. Missing it returns HTTP 400.
    refreshbooleanNoDefault false. When true, actually asks the source court portal for current orders instead of returning what is already stored, subject to the gates below. Not available on the Free tier: TIER_LIMITS.free.liveFetchAllowed is false, so a Free key sending refresh:true is refused before any work with LIVE_FETCH_NOT_ALLOWED. Tribunal cases are never live-fetchable regardless of tier; a stored-only read is all this endpoint can do for one, reported as liveFetchSupported: false.
    curl -X POST https://research.courtmesh.ai/api/v1/prod/request-timeline \
  -H "X-API-Key: cm-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"case_id": "507f1f77bcf86cd799439011"}'

# Ask for a genuine live fetch instead of the stored read (not on Free,
# not for tribunal cases, subject to its own per minute and per day caps):
curl -X POST https://research.courtmesh.ai/api/v1/prod/request-timeline \
  -H "X-API-Key: cm-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"case_id": "507f1f77bcf86cd799439011", "refresh": true}'
    GET

    /get-timeline/:requestId

    0 credits

    Poll the status of a timeline job. Status is one of pending, running, completed or failed. Completed jobs return the orders inline. Failed jobs carry an error string. Poll every few seconds and keep the polling inside your ten requests per minute budget, since this endpoint is priced at zero credits but still consumes a rate limit slot.

    curl https://research.courtmesh.ai/api/v1/prod/get-timeline/507f1f77bcf86cd799439012 \
  -H "X-API-Key: cm-YOUR_KEY_HERE"
    PreviousAI analysis
    NextLitigation check