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

> Get the summary results of a specific data diff via the Datafold API.

# Get a data diff summary



## OpenAPI

````yaml get /api/v1/datadiffs/{datadiff_id}/summary_results
openapi: 3.1.0
info:
  contact:
    email: support@datafold.com
    name: API Support
  description: >-
    The Datafold API reference is a guide to our available endpoints and
    authentication methods.

    If you're just getting started with Datafold, we recommend first checking
    out our [documentation](https://docs.datafold.com).


    :::info
      To use the Datafold API, you should first create a Datafold API Key,
      which should be stored as a local environment variable named DATAFOLD_API_KEY.
      This can be set in your Datafold Cloud's Settings under the Account page.
    :::
  title: Datafold API
  version: latest
servers:
  - description: Default server
    url: https://app.datafold.com
security:
  - ApiKeyAuth: []
paths:
  /api/v1/datadiffs/{datadiff_id}/summary_results:
    get:
      tags:
        - Data diffs
      summary: Get a data diff summary
      description: >-
        Structured counts for a completed data diff: primary-key stats, value
        stats, and — for

        same-database diffs — a `schema` section.


        The response shape depends on the diff's state and engine, so branch on
        `status` and on

        which sections are present rather than assuming a fixed payload:


        - `running` — only `status`. (The model also permits `pending`; the
        server does not
          currently emit it.)
        - `error` — `status` plus `error`.

        - `success` on a **same-database** diff — `ApiDataDiffSummaryForDone`,
        including `schema`.

        - `success` on a **cross-database** diff —
        `ApiCrossDataDiffSummaryForDone`, which has **no
          `schema` section**. Schema drift is not reported on this endpoint for cross-database
          diffs (nor by `diff_stats.diff_schema`, which is 0 for all of them); read it via the MCP
          tools `get_datadiff_overview` or `get_datadiff_result_section(section="columns")`.
      operationId: get_diff_summary_v1_api_v1_datadiffs__datadiff_id__summary_results_get
      parameters:
        - in: path
          name: datadiff_id
          required: true
          schema:
            title: Data diff id
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ApiDataDiffSummaryForDone'
                  - $ref: '#/components/schemas/ApiCrossDataDiffSummaryForDone'
                  - $ref: '#/components/schemas/ApiDataDiffSummaryForFailed'
                  - $ref: '#/components/schemas/ApiDataDiffSummaryForRunning'
                  - $ref: '#/components/schemas/InternalApiDataDiffDependencies'
                title: >-
                  Response Get Diff Summary V1 Api V1 Datadiffs  Datadiff Id 
                  Summary Results Get
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
components:
  schemas:
    ApiDataDiffSummaryForDone:
      description: >-
        Same-database (`join`, or unset algorithm) summary of a completed diff.
        Carries the

        `schema` section; its cross-database sibling
        `ApiCrossDataDiffSummaryForDone` does not —

        see that model for what is and isn't reported there.
      properties:
        created_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the diff was created.
          title: Created At
        data_source1_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: Data source of dataset A ("t1").
          title: Data Source1 Id
        data_source2_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: Data source of dataset B ("t2").
          title: Data Source2 Id
        dependencies:
          items:
            $ref: '#/components/schemas/ApiCIDependency'
          title: Dependencies
          type: array
        exclude_columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Columns excluded from the comparison.
          title: Exclude Columns
        exclusives_profile:
          anyOf:
            - $ref: '#/components/schemas/ApiExclusiveRowsProfile'
            - type: 'null'
          description: >-
            Distribution statistics for exclusive rows (rows that exist in one
            table but not the other). Includes histograms and enum distributions
            for primary key columns. Only available for diffs computed after
            October 2025.
        file1:
          anyOf:
            - type: string
            - type: 'null'
          description: File URI for dataset A, when compared as a file.
          title: File1
        file2:
          anyOf:
            - type: string
            - type: 'null'
          description: File URI for dataset B, when compared as a file.
          title: File2
        filter1:
          anyOf:
            - type: string
            - type: 'null'
          description: Row filter applied to dataset A.
          title: Filter1
        filter2:
          anyOf:
            - type: string
            - type: 'null'
          description: Row filter applied to dataset B.
          title: Filter2
        include_columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Columns compared (all shared columns if empty).
          title: Include Columns
        materialized_results:
          $ref: '#/components/schemas/ApiMaterializedResults'
          description: Results of the diff, materialized into tables.
        pk_columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Primary key column names used for this diff.
          title: Pk Columns
        pks:
          $ref: '#/components/schemas/ApiDataDiffSummaryPKs'
        query1:
          anyOf:
            - type: string
            - type: 'null'
          description: SQL for dataset A, when compared as a query.
          title: Query1
        query2:
          anyOf:
            - type: string
            - type: 'null'
          description: SQL for dataset B, when compared as a query.
          title: Query2
        sampling_ratio:
          anyOf:
            - type: number
            - type: 'null'
          description: Sampling ratio; null when the diff was not sampled.
          title: Sampling Ratio
        schema:
          $ref: '#/components/schemas/ApiDataDiffSummarySchema'
        status:
          enum:
            - done
            - success
          title: Status
          type: string
        table1:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Path segments of dataset A, when a table.
          title: Table1
        table2:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Path segments of dataset B, when a table.
          title: Table2
        values:
          anyOf:
            - $ref: '#/components/schemas/ApiDataDiffSummaryValues'
            - type: 'null'
      required:
        - status
        - pks
        - dependencies
        - schema
        - materialized_results
      title: ApiDataDiffSummaryForDone
      type: object
    ApiCrossDataDiffSummaryForDone:
      description: >-
        Cross-database counterpart of `ApiDataDiffSummaryForDone` (returned when
        the diff ran

        on a cross-database engine — any algorithm other than `join`; an unset
        algorithm is

        treated as same-database).


        Deliberately narrower than the same-database variant: there is **no
        `schema` field**,

        and `diff_stats.diff_schema` on the diff object is 0 for every
        cross-database diff.

        Neither field means "the schemas match" — schema drift is simply not
        reported on this

        surface. The comparison itself does compute a schema diff; to read it
        use the MCP tools

        `get_datadiff_overview` (its `schema` section) or
        `get_datadiff_result_section` with

        section="columns" (per-column types), both of which cover cross-database
        diffs.
      properties:
        created_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the diff was created.
          title: Created At
        data_source1_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: Data source of dataset A ("t1").
          title: Data Source1 Id
        data_source2_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: Data source of dataset B ("t2").
          title: Data Source2 Id
        exclude_columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Columns excluded from the comparison.
          title: Exclude Columns
        file1:
          anyOf:
            - type: string
            - type: 'null'
          description: File URI for dataset A, when compared as a file.
          title: File1
        file2:
          anyOf:
            - type: string
            - type: 'null'
          description: File URI for dataset B, when compared as a file.
          title: File2
        filter1:
          anyOf:
            - type: string
            - type: 'null'
          description: Row filter applied to dataset A.
          title: Filter1
        filter2:
          anyOf:
            - type: string
            - type: 'null'
          description: Row filter applied to dataset B.
          title: Filter2
        include_columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Columns compared (all shared columns if empty).
          title: Include Columns
        materialized_results:
          $ref: '#/components/schemas/ApiMaterializedResults'
          description: Results of the diff, materialized into tables.
        pk_columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Primary key column names used for this diff.
          title: Pk Columns
        pks:
          anyOf:
            - $ref: '#/components/schemas/ApiDataDiffSummaryPKs'
            - type: 'null'
        query1:
          anyOf:
            - type: string
            - type: 'null'
          description: SQL for dataset A, when compared as a query.
          title: Query1
        query2:
          anyOf:
            - type: string
            - type: 'null'
          description: SQL for dataset B, when compared as a query.
          title: Query2
        sampling_ratio:
          anyOf:
            - type: number
            - type: 'null'
          description: Sampling ratio; null when the diff was not sampled.
          title: Sampling Ratio
        status:
          enum:
            - done
            - success
          title: Status
          type: string
        table1:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Path segments of dataset A, when a table.
          title: Table1
        table2:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Path segments of dataset B, when a table.
          title: Table2
        values:
          anyOf:
            - $ref: '#/components/schemas/ApiDataDiffSummaryValues'
            - type: 'null'
      required:
        - status
      title: ApiCrossDataDiffSummaryForDone
      type: object
    ApiDataDiffSummaryForFailed:
      properties:
        error:
          anyOf:
            - $ref: '#/components/schemas/ApiDataDiffError'
            - additionalProperties: true
              type: object
          title: Error
        status:
          const: failed
          title: Status
          type: string
      required:
        - status
        - error
      title: ApiDataDiffSummaryForFailed
      type: object
    ApiDataDiffSummaryForRunning:
      properties:
        status:
          enum:
            - running
            - pending
          title: Status
          type: string
      required:
        - status
      title: ApiDataDiffSummaryForRunning
      type: object
    InternalApiDataDiffDependencies:
      properties:
        dependencies:
          items:
            $ref: '#/components/schemas/ApiCIDependency'
          title: Dependencies
          type: array
        status:
          enum:
            - done
            - success
          title: Status
          type: string
      required:
        - status
        - dependencies
      title: InternalApiDataDiffDependencies
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ApiCIDependency:
      properties:
        data_source_id:
          title: Data Source Id
          type: integer
        data_source_type:
          title: Data Source Type
          type: string
        item_type:
          title: Item Type
          type: string
        name:
          title: Name
          type: string
        path:
          items:
            type: string
          title: Path
          type: array
        popularity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Popularity
        primary_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Primary Key
        query_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Query Type
        raw_sql:
          anyOf:
            - type: string
            - type: 'null'
          title: Raw Sql
        remote_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Remote Id
        table_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Table Name
        uid:
          title: Uid
          type: string
      required:
        - uid
        - item_type
        - name
        - path
        - data_source_id
        - data_source_type
      title: ApiCIDependency
      type: object
    ApiExclusiveRowsProfile:
      properties:
        t1:
          anyOf:
            - $ref: '#/components/schemas/ApiTableProfile'
            - type: 'null'
          description: Profile for exclusive rows in table 1
        t2:
          anyOf:
            - $ref: '#/components/schemas/ApiTableProfile'
            - type: 'null'
          description: Profile for exclusive rows in table 2
      title: ApiExclusiveRowsProfile
      type: object
    ApiMaterializedResults:
      properties:
        diff:
          anyOf:
            - items:
                $ref: '#/components/schemas/ApiMaterializedResult'
              type: array
            - type: 'null'
          description: >-
            Results of row-to-row comparison between dataset A and B. Semantics
            is the same as for `exclusive_pks1` field.
          title: Diff
        duplicates1:
          anyOf:
            - items:
                $ref: '#/components/schemas/ApiMaterializedResult'
              type: array
            - type: 'null'
          description: >-
            Rows with duplicate primary keys detected in dataset A. Semantics is
            the same as for `exclusive_pks1` field.
          title: Duplicates1
        duplicates2:
          anyOf:
            - items:
                $ref: '#/components/schemas/ApiMaterializedResult'
              type: array
            - type: 'null'
          description: >-
            Rows with duplicate primary keys detected in dataset B. Semantics is
            the same as for `exclusive_pks1` field.
          title: Duplicates2
        exclusives:
          anyOf:
            - items:
                $ref: '#/components/schemas/ApiMaterializedResult'
              type: array
            - type: 'null'
          description: >-
            Rows with exclusive primary keys detected in dataset A and B. `None`
            if table is not ready yet or if materialization wasn't requested. If
            materialization is completed, for a diff inside a single database
            the field will contain a list with one element. If diff compares
            tables in different databases, the list may contain one or two
            entries.
          title: Exclusives
      title: ApiMaterializedResults
      type: object
    ApiDataDiffSummaryPKs:
      properties:
        distincts:
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: integer
            - type: integer
          title: Distincts
          type: array
        dupes:
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: integer
            - type: integer
          title: Dupes
          type: array
        exclusives:
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: integer
            - type: integer
          title: Exclusives
          type: array
        nulls:
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: integer
            - type: integer
          title: Nulls
          type: array
        total_rows:
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: integer
            - type: integer
          title: Total Rows
          type: array
      required:
        - total_rows
        - nulls
        - dupes
        - exclusives
        - distincts
      title: ApiDataDiffSummaryPKs
      type: object
    ApiDataDiffSummarySchema:
      description: >-
        Schema-comparison counts. Carried by `ApiDataDiffSummaryForDone`
        (same-database

        diffs) only — the cross-database variant has no `schema` field, see

        `ApiCrossDataDiffSummaryForDone`.


        Scope: column presence, column order, and data types. Nullability and
        other column

        constraints are **not** compared, so a column that only dropped `NOT
        NULL` counts as

        matching here.
      properties:
        column_counts:
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: integer
            - type: integer
          title: Column Counts
          type: array
        column_reorders:
          title: Column Reorders
          type: integer
        column_type_differs:
          items:
            type: string
          title: Column Type Differs
          type: array
        column_type_mismatches:
          title: Column Type Mismatches
          type: integer
        columns_mismatched:
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: integer
            - type: integer
          title: Columns Mismatched
          type: array
        exclusive_columns:
          items:
            items:
              type: string
            type: array
          title: Exclusive Columns
          type: array
      required:
        - columns_mismatched
        - column_type_mismatches
        - column_reorders
        - column_counts
        - column_type_differs
        - exclusive_columns
      title: ApiDataDiffSummarySchema
      type: object
    ApiDataDiffSummaryValues:
      properties:
        columns_diff_stats:
          items:
            $ref: '#/components/schemas/ApiColumnDiffStat'
          title: Columns Diff Stats
          type: array
        columns_with_differences:
          title: Columns With Differences
          type: integer
        compared_columns:
          title: Compared Columns
          type: integer
        rows_with_differences:
          title: Rows With Differences
          type: integer
        total_rows:
          title: Total Rows
          type: integer
        total_values:
          title: Total Values
          type: integer
        values_with_differences:
          title: Values With Differences
          type: integer
      required:
        - total_rows
        - rows_with_differences
        - total_values
        - values_with_differences
        - compared_columns
        - columns_with_differences
        - columns_diff_stats
      title: ApiDataDiffSummaryValues
      type: object
    ApiDataDiffError:
      properties:
        error_type:
          title: Error Type
          type: string
        error_value:
          title: Error Value
          type: string
        is_retryable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Retryable
      required:
        - error_type
        - error_value
      title: ApiDataDiffError
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    ApiTableProfile:
      description: Profile statistics for exclusive rows in one table.
      properties:
        columns:
          additionalProperties:
            $ref: '#/components/schemas/ApiColumnProfileStats'
          description: >-
            Map of column name to profile statistics. Only PK columns are
            included.
          title: Columns
          type: object
      required:
        - columns
      title: ApiTableProfile
      type: object
    ApiMaterializedResult:
      properties:
        data_source_id:
          description: Id of the DataSource the results were materialized into
          title: Data Source Id
          type: integer
        is_sampled:
          description: If sampling was applied
          title: Is Sampled
          type: boolean
        path:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            Path segments of the table. `None` when the destination is file
            storage, in which case `url` is set instead.
          title: Path
        url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Location of the materialized file, for object-storage destinations
            (S3/GCS/Azure Data Lake). `None` when the destination is a database,
            in which case `path` is set instead.
          title: Url
      required:
        - data_source_id
        - is_sampled
      title: ApiMaterializedResult
      type: object
    ApiColumnDiffStat:
      properties:
        column_name:
          title: Column Name
          type: string
        match:
          description: Percentage of cells that matched (0-100)
          title: Match
          type: number
        values_different:
          description: Count of different cells observed in the sample
          title: Values Different
          type: integer
        values_different_estimate:
          anyOf:
            - $ref: '#/components/schemas/ApiEstimatedIntValue'
            - type: 'null'
          description: >-
            Statistical estimate of differences for the full dataset. Only
            present when sampling was applied. Includes observed value,
            extrapolated estimate, confidence level, and confidence interval
            bounds.
      required:
        - column_name
        - match
        - values_different
      title: ApiColumnDiffStat
      type: object
    ApiColumnProfileStats:
      properties:
        distinct:
          anyOf:
            - type: integer
            - type: 'null'
          description: Approximate distinct value count
          title: Distinct
        histogram_bins:
          default: 0
          description: Number of histogram bins available (0 if no histogram)
          title: Histogram Bins
          type: integer
        max:
          anyOf:
            - type: string
            - type: 'null'
          description: Maximum value (formatted as string)
          title: Max
        min:
          anyOf:
            - type: string
            - type: 'null'
          description: Minimum value (formatted as string)
          title: Min
        nulls:
          description: Number of NULL values
          title: Nulls
          type: integer
        top_values_count:
          default: 0
          description: Number of top enum values available (0 if no enums)
          title: Top Values Count
          type: integer
        total:
          description: Total number of rows in exclusive set
          title: Total
          type: integer
      required:
        - total
        - nulls
      title: ApiColumnProfileStats
      type: object
    ApiEstimatedIntValue:
      properties:
        confidence:
          description: Confidence level (e.g., 0.95)
          title: Confidence
          type: number
        estimate:
          description: Estimated value for full dataset
          title: Estimate
          type: integer
        interval:
          $ref: '#/components/schemas/ApiEstimatedIntInterval'
          description: Confidence interval bounds
        value:
          description: Observed value in sample
          title: Value
          type: integer
      required:
        - value
        - estimate
        - confidence
        - interval
      title: ApiEstimatedIntValue
      type: object
    ApiEstimatedIntInterval:
      properties:
        max:
          title: Max
          type: integer
        min:
          title: Min
          type: integer
      required:
        - min
        - max
      title: ApiEstimatedIntInterval
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Use the 'Authorization' header with the format 'Key <api-key>'
      in: header
      name: Authorization
      type: apiKey

````