Deal queries

After you have initiated a deal and sent it to the buying party for review, you can query the deals object to check on the goals of the deal, activity of both parties, and the revision history. To reduce response times and optimize performance, use search features to filter and sort the deal information. For queries, see Deal query examples.

The following sections explain the available search results options and parameters and provide GraphQL examples that demonstrate how to query the Deals endpoint to retrieve deal information.

Deal search parameters

TIP: If you are new to GraphQL, check out the GraphQL API Resource Hub and familiarize yourself with the basics, such as query anatomy, authentication, rate limits, and more.

To improve your queries, add basic filters that specify what kind of information you are looking for, sort through the results of your queries and aggregate data over time.

Filtering

To reduce the number of responses and query complexity, use the where parameter. The following table lists all filterable properties in the deals object.

Here's an example deals query that shows how to filter for deals with the LIVE status within a flight.

NOTE: The status filter doesn't apply to negotiation status values.

query GetFilteredLiveDealsExample {
  deals(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER" }
    where: {
      dealStatus: {
        in: [LIVE]
      }
      lastUpdatedAtDateTimeRange: {
        gte: "2025-11-05T16:49:30.370Z"
        lt: "2025-11-20T04:59:00.000Z"
      }
      lastUpdatedBy: {
        eq: `BUYING_PARTY`
      }
    }
  )
}

NOTE: When you filter for paused or canceled deals, the deal status can take over a minute to update. To retrieve results in real-time, use the isCanceled or isPausedBySellingParty filters. For details, see the FAQ section in Manage Commitment Deal Performance or Pause and Resume Endeavors.

Sorting

To organize your data alphabetically, chronologically, or numerically, use the orderBy parameter. The following table lists all sortable properties in the deals object.

Here's an example deals query that shows how to sort deals by floor price in ascending order.

IMPORTANT: You can apply only one order operation at a time.

query GetSortedDealsByFloorPriceExample {
  deals(
      input: { accountId: "ACCOUNT_ID_PLACEHOLDER"}
      order: { floorPrice: ASC }
  ) {
    nodes {
      id
      floorPrice
    }
  }
}

Aggregating

To filter deals by a length of time or terms counted, use the aggregates parameter. The following table lists fields in the deals object that have aggregates for measurement.

Here's an example deals query that shows how to aggregate data from expanded deal terms.

query GetAggregatedExpandedDealsExample {
  deals(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER" }
  ) {
    aggregates(
      where: { performanceMetricsType: EXPANDED_TERMS }
    ) {
      totalMediaSpendUsd
    }
  }
}

The following table lists the deals.aggregates response fields.

Deal query examples

IMPORTANT: To run these examples, you must have your account ID assigned during onboarding. For details, see Get started with the PDP API for selling parties.

Here's what you need to know about retrieving deal information:

• For a list of all information that the deals query can retrieve, see Deal objects.
• When you query for financial terms, you must use the corresponding financialTerms object that matches your deal type.
• You can filter or sort your deal queries by name, date, or status. For details, see Deal search parameters.
• To view deal activity, you must also include the auditLog property.
• The revisionHistory object lists multiple versions of your deals. For the latest version, check the currentStatus property.
• Some query fields may differ from their related mutation fields.

The following sections provide GraphQL examples that demonstrate how to query the Deals endpoint to retrieve deal information. These queries use filters to return a list of all deals, deal terms for a deal, and the parties involved in each deal.

Retrieve your deals

The following deals query retrieves all deals that you have made.

query GetSellerDealsExample {
  deals(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER" }
  ) {
    totalCount
    nodes {
      dealType
      externallyManaged
      id
    }
  }
}

Retrieve commitment deal terms

The following deals query retrieves the terms of a commitment deal. To specify a deal, use the deal ID with a dealType value of COMMITMENT.

query GetCommitmentDealTermsExample {
  deals(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER" },
    where: {
      dealType: {
          in: [
              COMMITMENT
          ]
      }
    }
  ) {
    nodes {
      id
      dealType
      current {
        name
        terms {
          ... on CommitmentTerms {
            financialTerms {
              mediaSpendGoal
              minCpmPerSec
              nonDecisionedEligible
              nonDecisionedIneligibilityReasons
              minBidRate
              minWinRate
              minDailyAvails
            }
            cancellationTerms {
              threshold
              period
            }
            expansionTerms {
              threshold
              period
              floorPrice
            }
          }
        }
      }
      live {
        name
      }
      previous {
        name
      }
      auditLog {
        nodes {
          content   
        }
      }
    }
  }
}

Retrieve endeavor deal terms

The following deals query retrieves the terms of an endeavor deal. To specify a deal, use the deal ID with a dealType value of ENDEAVOR.

query GetEndeavorDealTermsExample {
  deals(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER" },
    where: {
      dealType: {
          in: [
              ENDEAVOR
          ]
      }
    }
  ) {
    nodes {
      id
      dealType
      current {
        name
        terms {
          ... on EndeavorTerms {
            financialTerms {
              mediaSpendGoal
              minCpmPerSec
            }
          }
        }
      }
      live {
        name
      }
      previous {
        name
      }
      auditLog {
        nodes {
          content
        }
      }
    }
  }
}

Retrieve deal parties

The following deals query retrieves the deal creation and acceptance dates, along with the contact information of both parties.

query GetDealPartiesExample {
  deals(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER" }
    where: {
      id: {
        in: ["DEAL_ID_PLACEHOLDER"]
      }
    }
  ) {
    nodes {
      accepted {
        at
        by {
          role
          contact {
            email
            name
          }
        }
      }
      created {
        at
        by {
          role
          contact {
            email
            name
          }
        }
      }
      sellingParty {
        contacts {
          email
          name
        }
      }
      buyingParty {
        contacts {
          email
          name
        }
        id
        name
        type
      }
    }
  }
}

Retrieve contributing deals

The following deals query retrieves a list of contributing deals for a primary deal, when applicable.

IMPORTANT: To retrieve contributing deals, you must also specify the current, live, or previous property.

query GetContributingDealExample {
  deals(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER" },
    where: {
      id: {
        in: ["PRIMARY_DEAL_ID_PLACEHOLDER"]
      }
    }
  ) {
    nodes {
      id
      dealType
      current {
        name
        contributingDeals {
          edges {
            node {
              deal {
                ... on Deal {
                  id
                  dealType
                }
              }
              isCurrentlyContributing
              lastUpdatedAt
              lastUpdatedBy {
                name
                email
              }
              attachedAt
              attachedBy {
                name
                email
              }
              isRemoved
            }
          }
        }
      }
    }
  }
}

Retrieve deal progress toward spend goals

To retrieve your deals with spend goals, use the aggregates property and query the deals object to return the measurements field. The aggregate can return information looking at all deal terms with OVERALL, but also supports splitting the base terms from the expanded terms.

The following deals query retrieves forecasted performance metrics for all deals with a spend goal.

query GetAllDealsSpendProgressExample {
  deals(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER" }
    aggregates(
      where: { performanceMetricsType: OVERALL }
    ) {
      totalForecastedUnderSpendUsd
      totalMediaSpendGoalUsd
      totalMediaSpendUsd
    }
  ) {
    nodes {
      measurements {
        forecastedUnderspendUsd
        performanceMetrics(
          where: {aggregate: TOTAL, performanceMetricsType: OVERALL}
        ) {
          availCount
          bidCount
          bidRatePercent
          cpm
          impressionCount
          startAt
          totalSpendUsd
          winRatePercent
        }
      }
    }
  }
}

Retrieve deal revision history

To retrieve your deal revision history, use the auditLog property and query the revision object. Every change made in a deal is tracked in the created object of the audit log. The audit log tracks the user that made the change, revision history, and the type of change.

The following deals query returns the deal revision history of all changes in a deal.

query GetDealAuditLogExample {
  deals(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER" }
    where: {
      id: {
        in: ["DEAL_ID_PLACEHOLDER"]
      }
    }
  ) {
    nodes {
      id
      auditLog {
        nodes {
          content
          type
          created {
            at
            by {
              role
              contact {
                email
                name
              }
            }
          }
          revision {
            revisionNumber
            dealNegotiationStatus
          }
        }
      }
    }
  }
}

Other queries

Outside of deal terms, there is more information that you can query to gauge the performance of your deal, inventory, and parties. The following table describes the other queries that can help you manage deals.