> ## Documentation Index
> Fetch the complete documentation index at: https://www.dataframer.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List failures

> List the failures DataFramer tracks in your production traces

A failure is a tracked finding marked as a failure — see [Root Causes & Remediation](/docs/findings/root-causes-and-remediation).


## OpenAPI

````yaml GET /api/dataframer/failures/
openapi: 3.0.0
info:
  title: DataFramer API
  version: 0.1.0
  description: ''
  termsOfService: https://www.aimon.ai/docs/privacy-policy.pdf
  contact:
    name: DataFramer Support
    email: info@dataframer.ai
  license:
    name: Proprietary
  x-logo:
    url: https://dataframer.ai/logo.png
    altText: DataFramer AI
  x-stainless:
    package-name: aimon-dataframer
    namespace:
      - aimon
      - dataframer
servers:
  - url: https://df-api.dataframer.ai
    description: Production server
security:
  - BearerAuth: []
externalDocs:
  description: Complete API Guide
  url: https://docs.dataframer.ai/dataframer
paths:
  /api/dataframer/failures/:
    get:
      summary: List failures
      description: >-
        List the failures DataFramer tracks in your production traces, newest
        first by when each was pinned to Tracking — not by recent activity, so a
        busy failure pinned long ago sorts last.


        Only tracked findings marked as a failure are returned.
      operationId: api_dataframer_failures_list
      parameters:
        - name: project_id
          in: query
          required: false
          description: Filter failures by which connected observability platform owns them
          schema:
            type: string
            format: uuid
        - name: updated_since
          in: query
          required: false
          description: Return only failures that changed after this time
          schema:
            type: string
            format: date-time
        - name: detail
          in: query
          required: false
          description: >-
            How much of each failure to return. `full` includes every root cause
            with its evidence, plus the expert-review and judge score blocks;
            `summary` returns counts only
          schema:
            type: string
            enum:
              - full
              - summary
            default: full
        - name: include
          in: query
          required: false
          description: >-
            Comma-separated extras. `reviews` and `judgments` add the submitted
            reviews and the judge verdicts themselves, which the list withholds
            by default because they dominate its size — their counts and
            averages are always present. `context` adds the knowledge and rubric
            content that `GET /api/dataframer/context/` serves, so one call gets
            both
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum failures to return
          schema:
            type: integer
            default: 50
            maximum: 200
        - name: offset
          in: query
          required: false
          description: Number of failures to skip
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: One page of failures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureListResponse'
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                bad_updated_since:
                  value:
                    error: >-
                      updated_since must be an ISO 8601 datetime with a
                      timezone, e.g. 2026-08-01T00:00:00Z
        '401':
          description: Unauthorized
      x-codeSamples:
        - lang: Python
          source: |-
            import os
            from dataframer import Dataframer

            client = Dataframer(
                api_key=os.environ.get("DATAFRAMER_API_KEY"),  # This is the default and can be omitted
            )
            failures = client.dataframer.failures.list()
            print(failures.context)
        - lang: cURL
          source: |-
            curl https://df-api.dataframer.ai/api/dataframer/failures/ \
                -H "Authorization: Bearer $DATAFRAMER_API_KEY"
components:
  schemas:
    FailureListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Failure'
        count:
          type: integer
          description: Total failures matching the filters
        context:
          allOf:
            - $ref: '#/components/schemas/ContextResponse'
          description: Knowledge and rubric content; returned only when `include=context`
    Failure:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Short name for the failure
        description:
          type: string
          description: What the traces in this failure have in common
        project:
          allOf:
            - $ref: '#/components/schemas/FailureProject'
          description: The project the traces came from
        trace_count:
          type: integer
          description: Traces currently assigned to this failure
        first_tracked_at:
          type: string
          format: date-time
          description: When the failure was first tracked
        last_refreshed_at:
          type: string
          format: date-time
          nullable: true
          description: When traces were last pulled and matched (null if never)
        rubrics:
          type: array
          items:
            $ref: '#/components/schemas/FailureRubricRef'
          description: >-
            Rubrics graded against on this failure's traces (omitted when
            `detail=summary`)
        human_review:
          allOf:
            - $ref: '#/components/schemas/FailureHumanReview'
          nullable: true
          description: Expert-review scores (null if none; omitted when `detail=summary`)
        llm_judge:
          allOf:
            - $ref: '#/components/schemas/FailureLlmJudge'
          nullable: true
          description: LLM-judge scores (null if none; omitted when `detail=summary`)
        analysis:
          allOf:
            - $ref: '#/components/schemas/FailureAnalysis'
          description: Automatic root-cause analysis
    ContextResponse:
      type: object
      properties:
        knowledge:
          allOf:
            - $ref: '#/components/schemas/ContextKnowledge'
          description: >-
            Knowledge distilled from your expert reviews. Always the whole
            workspace, never narrowed by `project_id`: policy, terminology and
            domain facts are meant to carry across projects. Absent entirely
            when `rubric_id` is given
        rubric_count:
          type: integer
          description: >-
            Rubrics your failures were graded against. When it exceeds the
            length of `rubrics`, that list is a trimmed view
        rubrics:
          type: array
          items:
            $ref: '#/components/schemas/ContextRubric'
          description: Those rubrics by name, each at its current version
    FailureProject:
      type: object
      description: The project a failure's traces come from
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Name of the project in DataFramer
        platform:
          type: string
          enum:
            - langfuse
            - langsmith
          description: Observability platform the traces are pulled from
    FailureRubricRef:
      type: object
      description: Reference to a grading rubric
      properties:
        id:
          type: string
          format: uuid
          description: ID of the rubric; its content is on `GET /api/dataframer/context/`
        name:
          type: string
          description: Name of the rubric
    FailureHumanReview:
      type: object
      description: Aggregated expert reviews of a failure's traces
      properties:
        reviewed_trace_count:
          type: integer
          description: Traces with at least one submitted review
        coverage:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Share of the failure's traces that were reviewed, 0-1. Often well
            below 1: a trace is reviewed only when someone chose to review it
        average_score:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          description: >-
            Mean review score per reviewed trace, 0-1 and higher is better (null
            if none scored). Averaged per trace, not per review, so a trace two
            people reviewed still counts once
        severity_distribution:
          type: object
          description: >-
            Reviews at each severity, counting each review once at its worst
            grade. The levels run low, medium, high, critical — critical is the
            worst
          properties:
            low:
              type: integer
            medium:
              type: integer
            high:
              type: integer
            critical:
              type: integer
        review_count:
          type: integer
          description: >-
            Submitted reviews that exist, one per trace and reviewer — the true
            total behind the `reviews` sample
        reviews:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/FailureReview'
          description: >-
            Submitted reviews, newest first, and a sample rather than the whole
            set — when `review_count` exceeds the number here, you are reading a
            trimmed view. On the list, returned only with `include=reviews`
    FailureLlmJudge:
      type: object
      description: Aggregated LLM-judge verdicts on a failure's traces
      properties:
        judged_trace_count:
          type: integer
          description: Traces with at least one judge verdict
        coverage:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Share of the failure's traces that were judged, 0-1. Often well
            below 1: a trace is judged only when a judge run covered it
        average_score:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          description: >-
            Mean judge score per judged trace, 0-1 and higher is better (null if
            none scored). Not comparable with the expert-review average unless
            both graded the same traces against the same rubric
        judgment_count:
          type: integer
          description: >-
            Verdicts that exist, one per trace and judge — the true total behind
            the `judgments` sample
        judgments:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/FailureJudgment'
          description: >-
            Verdicts, newest first, and a sample rather than the whole set —
            when `judgment_count` exceeds the number here, you are reading a
            trimmed view. On the list, returned only with `include=judgments`
    FailureAnalysis:
      type: object
      description: Automatic root-cause analysis of a failure
      properties:
        status:
          type: string
          enum:
            - never_run
            - analyzing
            - ready
            - failed
          description: State of the analysis; `failed` means there are no causes to show
        last_analyzed_at:
          type: string
          format: date-time
          nullable: true
          description: When analysis last completed (null if never)
        new_traces_since_analysis:
          type: integer
          nullable: true
          description: Traces added since `last_analyzed_at` (null if never analyzed)
        cause_count:
          type: integer
          description: >-
            Active causes that exist. When it exceeds the length of `causes`,
            that list is a trimmed view
        prompt_template_count:
          type: integer
          description: >-
            Prompt templates that exist, read the same way against
            `prompt_templates`; returned only when `detail=full`
        prompt_templates:
          type: array
          items:
            $ref: '#/components/schemas/InferredPromptTemplate'
          description: >-
            Prompt templates inferred from your traces; returned only when
            `detail=full`. May be trimmed — compare against
            `prompt_template_count`
        causes:
          type: array
          items:
            $ref: '#/components/schemas/RootCause'
          description: >-
            Root causes including retired and archived ones, most-attributed
            first; returned only when `detail=full`. May be trimmed — compare
            against `cause_count`
    ContextKnowledge:
      type: object
      description: Distilled knowledge for the whole workspace, never scoped to one project
      properties:
        facts:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/KnowledgeFact'
          description: >-
            Facts, newest first, and a sample rather than the whole set —
            compare against `total`
        total:
          type: integer
          description: >-
            Facts that exist, before the newest-first trim — the true total
            behind the `facts` sample
    ContextRubric:
      type: object
      description: One rubric's current content
      properties:
        id:
          type: string
          format: uuid
          description: Referenced by `rubrics[].id` on failures
        name:
          type: string
          description: Name of the rubric
        project:
          allOf:
            - $ref: '#/components/schemas/FailureProject'
          description: The project the rubric belongs to
        version:
          type: integer
          description: Version number served
        description:
          type: string
          description: Description of the rubric
        instructions:
          type: string
          description: The team's grading guidance
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/ContextRubricDimension'
          description: Scoring axes of the rubric
        examples_omitted:
          type: integer
          description: >-
            Examples left out of this response. Re-request this rubric with the
            `rubric_id` query parameter to get all of them
    FailureReview:
      type: object
      description: One reviewer's submitted review of one trace
      properties:
        source_id:
          type: string
          description: The trace's ID in your observability platform
        source_url:
          type: string
          format: uri
          nullable: true
          description: Deep link to the trace (null if no link can be built)
        reviewer:
          type: object
          description: The team member who submitted the review, by name and email address
          properties:
            name:
              type: string
              description: Reviewer's display name
            email:
              type: string
              format: email
              description: Reviewer's email address
        submitted_at:
          type: string
          format: date-time
          description: When the review was submitted
        grades:
          type: array
          items:
            $ref: '#/components/schemas/FailureReviewGrade'
          description: One entry per rubric graded
        trace_edits:
          type: array
          items:
            $ref: '#/components/schemas/FailureReviewTraceEdit'
          description: One entry per part of the trace marked up
    FailureJudgment:
      type: object
      description: One LLM judge's verdict on one trace
      properties:
        source_id:
          type: string
          description: The trace's ID in your observability platform
        source_url:
          type: string
          format: uri
          nullable: true
          description: Deep link to the trace (null if no link can be built)
        judge:
          type: object
          description: The judge that produced the verdict
          properties:
            id:
              type: string
              format: uuid
              description: >-
                Unique identifier for the judge, as on `GET
                /api/dataframer/judges/`
            name:
              type: string
              description: Name of the judge
            model:
              type: string
              description: Model the judge runs on
        rubric:
          type: string
          description: Name of the rubric graded against
        rubric_id:
          type: string
          format: uuid
          description: ID of the rubric; its content is on `GET /api/dataframer/context/`
        evaluated_at:
          type: string
          format: date-time
          description: When the judge run that produced this verdict completed
        overall_score:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          description: Mean score across the graded dimensions (null if none resolved)
        confidence:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          description: The judge's self-reported confidence (null if not given)
        verdicts:
          type: array
          description: The judge's pick per rubric dimension
          items:
            type: object
            properties:
              dimension:
                type: string
                description: Name of the rubric dimension
              score:
                oneOf:
                  - type: string
                  - type: array
                    items:
                      type: string
                description: Label of the picked level, or labels for checklist dimensions
              notes:
                type: string
                description: The judge's reasoning for this dimension
    InferredPromptTemplate:
      type: object
      description: A prompt template reconstructed from your traces
      properties:
        group:
          type: string
          description: Label for the traces sharing this template
        template:
          type: string
          description: The reconstructed text, with placeholders for the parts that vary
        trace_count:
          type: integer
          description: Analyzed traces produced with this template
        notes:
          type: string
          description: Anything notable about the reconstruction
    RootCause:
      type: object
      description: One explanation for why a failure happens
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - active
            - retired
            - archived
          description: >-
            Whether analysis still finds this cause; `archived` means dismissed
            in the app
        rank:
          type: integer
          description: Position in the cause list, by attributed traces
        title:
          type: string
          description: One-line statement of the cause
        description:
          type: string
          description: The full explanation of what goes wrong and where
        probability:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence that this cause explains the failure
        attributed_trace_count:
          type: integer
          description: Traces attributed to this cause, among those analysis sampled
        first_detected_at:
          type: string
          format: date-time
          description: When the cause was first produced
        last_confirmed_at:
          type: string
          format: date-time
          description: When analysis last found traces with this cause
        updated_at:
          type: string
          format: date-time
          description: When the cause was last changed
        remediation:
          allOf:
            - $ref: '#/components/schemas/RootCauseRemediation'
          nullable: true
          description: The suggested fix (null if none was confident enough)
        examples:
          type: array
          items:
            $ref: '#/components/schemas/RootCauseExample'
          description: Places in your traces where the cause shows up
    KnowledgeFact:
      type: object
      description: One claim about your domain, distilled by an LLM from an expert review
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          example: policy_rule
          description: What sort of claim this is
        text:
          type: string
          description: The claim itself
        grounding:
          type: string
          description: Excerpts from the source trace that support the claim
        tags:
          type: array
          items:
            type: string
          description: Tags on the fact
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence in the claim
        created_at:
          type: string
          format: date-time
          description: When the fact was distilled
        source:
          type: object
          nullable: true
          description: The trace the fact came from (null if it no longer resolves)
          properties:
            source_id:
              type: string
              description: The trace's ID in your observability platform
            source_url:
              type: string
              format: uri
              nullable: true
              description: Deep link to the trace (null if no link can be built)
    ContextRubricDimension:
      type: object
      description: One scoring axis of a rubric
      properties:
        name:
          type: string
          description: Name of the dimension
        scoring_model:
          type: string
          enum:
            - pass_fail
            - scale_1_5
            - single_select
            - checklist
          description: How the dimension is scored
        required:
          type: boolean
          description: Whether reviewers must grade this dimension
        levels:
          type: array
          description: The choosable verdicts for this dimension
          items:
            type: object
            properties:
              label:
                type: string
                description: Label shown to reviewers
              description:
                type: string
                nullable: true
                description: Guidance for the level (null if none)
              value:
                type: number
                nullable: true
                description: Numeric value for scale levels (null for other scoring models)
        positive_examples:
          type: array
          items:
            $ref: '#/components/schemas/RubricExample'
          description: Examples of a pass (pass/fail and scale dimensions)
        negative_examples:
          type: array
          items:
            $ref: '#/components/schemas/RubricExample'
          description: Examples of a fail (pass/fail and scale dimensions)
        examples:
          type: array
          items:
            $ref: '#/components/schemas/RubricExample'
          description: >-
            Neutral calibration examples (checklist and single-select
            dimensions)
    FailureReviewGrade:
      type: object
      description: A reviewer's grade against one rubric
      properties:
        rubric:
          type: string
          description: Name of the rubric
        rubric_id:
          type: string
          format: uuid
          description: ID of the rubric; its content is on `GET /api/dataframer/context/`
        severity:
          type: string
          enum:
            - low
            - medium
            - high
            - critical
          nullable: true
          description: Severity picked (null if the rubric collects none)
        rationale:
          type: string
          description: The reviewer's rationale, often empty
        scores:
          type: array
          description: The reviewer's pick per rubric dimension
          items:
            type: object
            properties:
              dimension:
                type: string
                description: Name of the rubric dimension
              score:
                oneOf:
                  - type: string
                  - type: array
                    items:
                      type: string
                description: Label of the picked level, or labels for checklist dimensions
              confidence:
                type: string
                enum:
                  - low
                  - medium
                  - high
                nullable: true
                description: How confident the reviewer was (null if not given)
    FailureReviewTraceEdit:
      type: object
      description: A reviewer's markup of one part of a trace
      properties:
        area:
          type: string
          enum:
            - query
            - answer
            - prompt
            - rubric_feedback
            - step_input
            - step_output
            - step_reasoning
            - step_retrieval
          description: Which part of the trace the markup targets
        step_name:
          type: string
          nullable: true
          description: Name of the pipeline step (null for whole-trace areas)
        status:
          type: string
          enum:
            - ok
            - wrong
            - incomplete
            - unsupported
            - ambiguous
            - bad_or_unclear_query
            - rubric_insufficient
            - missing_context
          nullable: true
          description: The reviewer's verdict on this part (null if none given)
        rationale:
          type: string
          description: The reviewer's note on this part
        diff:
          type: string
          nullable: true
          description: The reviewer's rewrite, as a unified diff (null if none)
    RootCauseRemediation:
      type: object
      description: A suggested fix for one root cause
      properties:
        instructions:
          type: string
          description: What to change in your application
        prompt_template_edits:
          type: array
          items:
            $ref: '#/components/schemas/PromptTemplateEdit'
          description: >-
            Edits to your prompt templates (empty if the fix is not a prompt
            change)
        probability:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence that this fix removes the cause
    RootCauseExample:
      type: object
      description: A citation into one of your traces
      properties:
        source_id:
          type: string
          description: >-
            The trace's ID in your observability platform. Depending on the
            project's ingestion granularity this is natively a trace,
            observation, or session ID
        source_url:
          type: string
          format: uri
          nullable: true
          description: Deep link to the trace (null if no link can be built)
        quote:
          type: string
          description: >-
            Verbatim text from the trace (empty if no exact quote could be
            extracted)
        occurred_at:
          type: string
          format: date-time
          description: When the trace happened
    RubricExample:
      type: object
      description: One calibration example from a reviewed trace
      properties:
        query:
          type: string
          description: The example trace's input
        answer:
          type: string
          description: The example trace's output
        source_id:
          type: string
          nullable: true
          description: >-
            The trace's ID in your observability platform (null if it no longer
            resolves)
        source_url:
          type: string
          format: uri
          nullable: true
          description: Deep link to the trace (null if no link can be built)
    PromptTemplateEdit:
      type: object
      description: One before/after edit to a prompt template
      properties:
        template_ref:
          type: string
          description: Matches the `group` of an entry in `analysis.prompt_templates`
        before:
          type: string
          description: The passage as it stands today
        after:
          type: string
          description: The suggested rewrite
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key authentication. Format: "Bearer YOUR_API_KEY"'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.