Skip to main content

Documentation Index

Fetch the complete documentation index at: https://jdcodec.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

JD Codec talks about three nested units: sessions, tasks, and steps. They show up in the API, your usage data, and your bill. The easiest way to picture them is the nesting: a session contains a task; a task contains steps.

​
A concrete example

Imagine you ask your AI agent to find the highest-rated wireless headphones under $200 on a major retailer. The connector opens one session in the cloud the moment your agent starts working. Inside that session, “find me the best headphones under $200” is one task — one thing the user is trying to get done. Inside that task, every time the agent reads the browser page, that’s one step — load the homepage, search “wireless headphones”, scan results, click into the top product, read its reviews, go back, click into the next, compare, recommend. One session, one task, roughly ten steps. The first step is the full picture (a keyframe). Every step after that is just what changed (a delta). Your agent sees a much smaller representation of the page on every step except the first. Your bill counts one task. Visualised: 
session  (in-memory model of the page, opens for the agent's run)
└── task  ("find me the best headphones under $200")
    ├── step 0: keyframe       (full snapshot ~ 30k chars)
    ├── step 1: delta          (search query entered ~ 2k chars)
    ├── step 2: delta          (results page loaded ~ 3k chars)
    ├── step 3: delta          (clicked into product 1 ~ 5k chars)
    ├── step 4: delta          (scrolled to reviews ~ 400 chars)
    ├── ...
    └── step N: delta          (final answer composed)
Numbers are illustrative — actual sizes depend on the page and how much changed. The pattern holds: keyframe is full-sized, every delta after is a small fraction.

​
Sessions

A session is JD Codec’s running memory of your page structure. The cloud holds an in-memory model of what the agent saw last so the next snapshot can be sent as a delta — only what changed since last time. Sessions are scoped to your agent’s continuous run. They expire after:
  • 30 minutes of inactivity, or
  • 4 hours total, whichever comes first.
After expiry, the next request opens a fresh session and the codec starts over from a keyframe. The connector handles this transparently — your agent doesn’t need to know. If your workload runs unusually long sessions or unusually short ones, per-key TTL overrides are available. Talk to support at [email protected].

​
Tasks

A task is one user-meaningful unit of work — book a flight, fill out a form, compare three products, scrape a page. A task is your agent’s intent. It usually spans many steps. Tasks are the billing unit. Per-task pricing decouples your cost from the number of internal browser snapshots a task happens to require — your bill scales with the work your agent does, not with how many steps it takes to do it. A task is fully contained within one session. Tasks can’t span sessions: if a session expires mid-task, the next request opens a fresh session and a fresh task automatically.

​
Steps

A step is a single browser snapshot — every time your agent reads the page. Steps are numbered within a session, starting at 0, and the numbers always go up. Sending an out-of-order step number returns step_out_of_order. Per-step compression numbers (input_chars, output_chars, codec_ms) are recorded server-side in your usage data. They tell you exactly how the codec performed on each snapshot — useful for spotting which page transitions compress well and which trigger pass-through (where the codec decides compression wouldn’t help). A self-serve dashboard for browsing usage data is on the roadmap. Until it ships, request a usage export by emailing [email protected] with your api_key_id. The first step in every session is always a keyframe — the full page state. Every step after that is a delta — just what changed.

​
What you control

If you’re using the connector (most users): nothing. Session IDs, task IDs, and step numbers are generated and tracked for you. Session expiry, retries on expiry, and step ordering are all automatic. If you’re integrating directly against the API (advanced users — typically when building a custom connector): you generate UUIDs for session_id and task_id and pass them on each request. The API Reference covers the wire-level details.

​
Why this matters

The unit framing isn’t just plumbing — it’s how JD Codec thinks about value. Steps are where compression happens. Tasks are how value is measured (one task = one user outcome). Sessions are the technical scope that makes deltas possible. When your usage data shows “this task ran 12 steps, average 87% compression, one keyframe at the start,” that’s the framing in action: one billable outcome, twelve internal measurements, one continuous codec session keeping deltas tight.