Lenses

A lens is a reusable analysis configuration: it tells Intelligence what to look for in a recording and what shape the answer must have. The same lens produces the same structure for every recording it analyzes, so you can store, compare, and automate on its results.

A lens belongs to your company and can be activated in any of its environments. Every change is versioned, and each analysis records the exact version it used.

Creating and Editing Lenses

Lenses are created and edited in the dashboard with the Designer: open Intelligence → + New lens, or Edit with the Designer on an existing lens. The Designer reads a sample recording (or your description), proposes lenses that fit, and asks a few questions to refine the one you choose. Everything it writes stays editable on the draft board, and drafts are saved automatically.

You can also design, edit, publish, and activate lenses from your AI assistant with the VIDTREO MCP.

This page documents every building block of a lens — what it does, its limits, and how it shows up in the result — so you can design lenses deliberately and read their results with confidence.

Anatomy of a Lens

Instructions, output language, and visual checks have no form of their own: ask the Designer for them in the conversation (for example, "Write the report in Spanish" or "Check whether a slide is being shared"). They appear in the lens's version history as Instructions, Report language, and On-screen checks.

The configuration keys below (objective, fields, rubric...) are the names used in the lens configuration and in the result. Every result also includes a summary, speakers, chapters, and quality checks, whatever the lens configuration — see the Result reference.

Example

A complete configuration for screening job candidates from a recorded video answer:

{
  "objective": "Evaluate a candidate's recorded answer for a backend engineering role: background, motivation, and fit.",
  "instructions": "The candidate answers a single prompt. Focus on concrete experience and avoid judging accent or appearance.",
  "outputLanguage": "en",
  "summarySections": ["Background", "Motivation", "Concerns"],
  "fields": [
    { "name": "years_of_experience", "type": "number", "description": "Years of professional backend experience the candidate states." },
    { "name": "willing_to_relocate", "type": "boolean", "description": "Whether the candidate says they are willing to relocate." },
    { "name": "english_level", "type": "enum", "description": "Spoken English level shown in the recording.", "enumValues": ["basic", "intermediate", "advanced", "native"] },
    { "name": "tools_mentioned", "type": "array", "itemType": "text", "description": "Languages, databases, and tools the candidate mentions using." },
    { "name": "reads_from_notes", "type": "boolean", "description": "Whether the candidate appears to read from notes or another screen." }
  ],
  "rubric": [
    { "id": "communication", "label": "Communication", "maxScore": 5, "description": "Clear, structured answers with concrete examples." },
    { "id": "technical_depth", "label": "Technical depth", "maxScore": 5, "description": "Explains architecture decisions, trade-offs, and results." }
  ],
  "scale": 10,
  "trustRules": [
    { "id": "no_protected_traits", "description": "Never comment on age, gender, ethnicity, accent, or appearance." }
  ],
  "visualChecks": [
    { "id": "looks_off_screen", "question": "Is the candidate repeatedly looking away from the camera, as if reading?" }
  ]
}

Objective

objective · string · required · up to 4,000 characters

One or two sentences describing what the analysis is for. It frames everything else the lens extracts. A lens with an empty objective cannot be published.

"Qualify inbound sales calls: needs, budget, timeline, and decision makers."

Instructions

instructions · string · optional · up to 8,000 characters

Context and interpretation guidance: who is speaking, what a good answer looks like, domain vocabulary, what to ignore.

Output Language

outputLanguage · "auto" | "en" | "es" · default "auto"

The language of every text value in the result — summary, points, chapters, field values, and rubric feedback. With auto, the result is written in the main language spoken in the recording. Set a fixed language when your downstream systems or reviewers expect one language regardless of what is spoken — for example, English reports for Spanish-language interviews.

Summary Sections

summarySections · string[] · up to 20 sections · up to 200 characters each

The headings of the written summary. Each section comes back in result.sections[], in the same order, with labeled points that cite their evidence. Sections are semantic: they cover the whole recording, not a time range.

If no sections are configured, the result contains a single Summary section. Duplicate titles are merged.

Fields

fields · array · up to 50 fields

Structured values extracted from the recording. Each field becomes one entry in result.findings[].

How each type is returned:

Every value comes with a status (supported, insufficient_evidence, or contradictory) and the evidence behind it. A value that cannot be backed by the recording is returned as null — never guessed. See Reading field values.

Rubric and Scale

rubric · array · up to 30 criteria · scale · number | null

A rubric turns the lens into a scorecard. Each criterion is scored from 0 to its maxScore, with written feedback and the evidence that justifies the score.

scale is optional. When omitted, it is the sum of every maxScore. When set, it must equal that sum (for example, two criteria of 5 require a scale of 10).

How scoring works:

• The model scores each criterion individually; VIDTREO computes the total. The model never adds up scores.
• A criterion scored without valid evidence is discarded (score: null, downgraded: true).
• scorecard.total is only set when every criterion has a score (complete: true). Otherwise it is null, and the run's display score reads incomplete score.
• When an expected element is absent from the recording (for example, an answer with no conclusion), the criterion is scored low with evidence of the absence rather than skipped.

Trust Rules

trustRules · array · up to 30 rules

Rules the analysis must always follow, written in plain language. Use them for compliance and fairness constraints that must hold for every recording.

"Never comment on age, gender, ethnicity, accent, or appearance." "Do not infer a budget that the customer did not state."

These are applied on top of the rules every analysis already follows: use only what is in the recording, cite evidence for every claim, and answer insufficient_evidence instead of guessing.

Visual Checks

visualChecks · array · up to 20 checks

Yes/no questions answered from what appears on screen: slides, shared screens, the people in frame, the environment.

When a lens has at least one visual check and the recording is a video, the analysis adds a vision step: VIDTREO extracts keyframes from the video, skips frames where nothing changes, and reviews the rest. The observations feed the analysis, which can then cite frames (F<n>) as evidence. On recordings with several speakers, frames are also used to help put names to voices (P<n> evidence).

To expose a visual answer as a structured value for your integration, pair the check with a boolean field, as the reads_from_notes field and the looks_off_screen check do in the example.

Artifacts

artifacts · array · up to 30 items

The parts of the report each analysis shows in the dashboard — What each analysis includes in the Designer — such as Summary, Findings, Scorecard, Chapters, Key Moments, and Evidence. Add them with Add artifact, or describe your own with Custom artifact. Coverage (support, abstention, and contradiction report) and Manifest (version and run metadata) are always generated.

Artifacts only affect presentation in the dashboard. They do not change what is extracted, and the webhook always delivers the complete result.

Limits

The platform accepts the limits listed in each section above. Lenses written by the Designer are kept within tighter limits that also make good practice:

Validation

A lens version must pass these checks before it can be published or used for an analysis:

Versions

Lenses are versioned so that changing a lens never silently changes past or in-flight results.

• Publish (or Publish changes) validates the configuration (see Validation) and makes the version available. When the lens is already active, publishing a new version moves its activations to that version.
• To go back to an earlier version, open the lens's History tab, select the version, and click Use this version. Use Compare two versions to see exactly what changed between them.
• A version switch applies to every environment where the lens is active. Analyses already queued or in progress keep the version they started with.
• Every analysis stores the version it used, and the webhook includes it in data.run.lensVersionId — store it next to the result to know which configuration produced it.

Which version analyzes a recording

1. When the lens is active in the recording's environment, the activated version — for automatic and manual analyses alike
2. Otherwise, the latest published version of the lens

A lens with no published version cannot analyze recordings: Publish the lens before analyzing videos with it.

Writing Effective Lenses

• One lens, one job. A focused lens ("Sales discovery call") produces sharper results than a catch-all. Activate several lenses in the same environment when you need several perspectives — each produces its own run and webhook.
• Describe fields like you would brief a colleague. The description is what the analysis reads: say what counts, what does not, and in what unit ("Monthly budget in USD as stated by the customer").
• Prefer enum over free text for anything your code branches on, and validate the value on your side.
• Make rubric descriptions observable. "Gives at least one concrete example with a measurable result" scores more consistently than "Good answer".
• Use trust rules for non-negotiables — fairness, compliance, and what must never be inferred.
• Test with real recordings before activating. Publish the lens without choosing environments, use Analyze a recording on a handful of real recordings, review the evidence in the dashboard, then activate it with auto-analyze.