A bid simulation contains **simulation data** and information about the time
range, **type of simulation data** , and the campaign, ad group, ad group
criterion, or bidding strategy to which it applies. The simulation data is a
sequence of **simulation points** that provides a histogram of predicted
performance with different bids, targets, or budgets during the given
timeframe. The information provided by a simulation point depends on the type
of simulation data.

> [!IMPORTANT]
> **Key Point:** The time range is always in the past, as bid simulations predict how your ads would have performed at those times and under the same conditions, but with different bids.

You can retrieve any bid simulation with a Google Ads Query Language query by selecting the
appropriate **simulation data field** (type of simulation data) from the
corresponding **resource** (bid level).

> [!IMPORTANT]
> **Key Point:** Each bid level is associated with a specific set of supported combinations of field values. Refer to the documentation of each resource type for more details, such as [`CampaignSimulation`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignSimulation.md.txt).

| Bid Level \& Resource | [`SimulationType`](https://developers.google.com/google-ads/api/reference/rpc/v26/SimulationTypeEnum.SimulationType.md.txt) | Simulation Data Field | Simulation Point Type |
|---|---|---|---|
| **Ad Group** [`ad_group_simulation`](https://developers.google.com/google-ads/api/fields/v26/ad_group_simulation.md.txt) | `CPC_BID` `CPV_BID` `TARGET_CPA` `TARGET_ROAS` | [`ad_group_simulation.cpc_bid_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/ad_group_simulation.md.txt#ad_group_simulation.cpc_bid_point_list.points) [`ad_group_simulation.cpv_bid_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/ad_group_simulation.md.txt#ad_group_simulation.cpv_bid_point_list.points) [`ad_group_simulation.target_cpa_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/ad_group_simulation.md.txt#ad_group_simulation.target_cpa_point_list.points) [`ad_group_simulation.target_roas_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/ad_group_simulation.md.txt#ad_group_simulation.target_roas_point_list.points) | [`CpcBidSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/CpcBidSimulationPoint.md.txt) [`CpvBidSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/CpvBidSimulationPoint.md.txt) [`TargetCpaSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/TargetCpaSimulationPoint.md.txt) [`TargetRoasSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/TargetRoasSimulationPoint.md.txt) |
| **Ad Group Criterion** [`ad_group_criterion_simulation`](https://developers.google.com/google-ads/api/fields/v26/ad_group_criterion_simulation.md.txt) | `CPC_BID` `PERCENT_CPC_BID` | [`ad_group_criterion_simulation.cpc_bid_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/ad_group_criterion_simulation.md.txt#ad_group_criterion_simulation.cpc_bid_point_list.points) [`ad_group_criterion_simulation.percent_cpc_bid_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/ad_group_criterion_simulation.md.txt#ad_group_criterion_simulation.percent_cpc_bid_point_list.points) | [`CpcBidSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/CpcBidSimulationPoint.md.txt) [`PercentCpcBidSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/PercentCpcBidSimulationPoint.md.txt) |
| **Bidding Strategy (portfolio)** [`bidding_strategy_simulation`](https://developers.google.com/google-ads/api/fields/v26/bidding_strategy_simulation.md.txt) | `TARGET_CPA` `TARGET_ROAS` | [`bidding_strategy_simulation.target_cpa_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/bidding_strategy_simulation.md.txt#bidding_strategy_simulation.target_cpa_point_list.points) [`bidding_strategy_simulation.target_roas_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/bidding_strategy_simulation.md.txt#bidding_strategy_simulation.target_roas_point_list.points) | [`TargetCpaSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/TargetCpaSimulationPoint.md.txt) [`TargetRoasSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/TargetRoasSimulationPoint.md.txt) |
| **Campaign** [`campaign_simulation`](https://developers.google.com/google-ads/api/fields/v26/campaign_simulation.md.txt) | `BUDGET` `CPC_BID` `TARGET_CPA` `TARGET_IMPRESSION_SHARE` `TARGET_ROAS` | [`campaign_simulation.budget_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/campaign_simulation.md.txt#campaign_simulation.budget_point_list.points) [`campaign_simulation.cpc_bid_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/campaign_simulation.md.txt#campaign_simulation.cpc_bid_point_list.points) [`campaign_simulation.target_cpa_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/campaign_simulation.md.txt#campaign_simulation.target_cpa_point_list.points) [`campaign_simulation.target_impression_share_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/campaign_simulation.md.txt#campaign_simulation.target_impression_share_point_list.points) [`campaign_simulation.target_roas_point_list.points`](https://developers.google.com/google-ads/api/fields/v26/campaign_simulation.md.txt#campaign_simulation.target_roas_point_list.points) | [`BudgetSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/BudgetSimulationPoint.md.txt) [`CpcBidSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/CpcBidSimulationPoint.md.txt) [`TargetCpaSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/TargetCpaSimulationPoint.md.txt) [`TargetImpressionShareSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/TargetImpressionShareSimulationPoint.md.txt) [`TargetRoasSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/TargetRoasSimulationPoint.md.txt) |

> [!NOTE]
> **Note:** In `CampaignSimulation`, the simulated metrics populated on each point can vary by advertising channel. For example, Demand Gen (`DEMAND_GEN`) campaigns populate `interactions` instead of `clicks` on `TargetCpaSimulationPoint`, and App (`MULTI_CHANNEL`) campaigns populate `app_installs` and `in_app_actions` on `TargetCpaSimulationPoint`.

## Scaled simulation modification method in campaign simulations

Each simulation resource includes a `modification_method` field of type
[`SimulationModificationMethod`](https://developers.google.com/google-ads/api/reference/rpc/v26/SimulationModificationMethodEnum.SimulationModificationMethod.md.txt) that indicates
how the simulated values are applied (`UNIFORM`, `DEFAULT`, or `SCALING`). While
`UNIFORM` and `DEFAULT` simulations populate explicit micro amounts on each
simulation point (such as `cpc_bid_micros` or `target_cpa_micros`),
campaign-level simulations for Search campaigns also support a
[`SCALING`](https://developers.google.com/google-ads/api/reference/rpc/v26/SimulationModificationMethodEnum.SimulationModificationMethod.md.txt#scaling) modification method for both `CPC_BID` and
`TARGET_CPA` simulations:

- When [`CampaignSimulation.type`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignSimulation.md.txt#type) is `CPC_BID` and `modification_method` is `SCALING`, each [`CpcBidSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/CpcBidSimulationPoint.md.txt) populates `cpc_bid_scaling_modifier` (instead of `cpc_bid_micros`) to show what happens if all CPC bids in the campaign (both ad group default CPC bids and criterion-level CPC bids) are scaled by that modifier. For example, a scaling modifier of `2.0` shows what happens if all CPC bids in the campaign are doubled.
- When [`CampaignSimulation.type`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignSimulation.md.txt#type) is `TARGET_CPA` and `modification_method` is `SCALING`, each [`TargetCpaSimulationPoint`](https://developers.google.com/google-ads/api/reference/rpc/v26/TargetCpaSimulationPoint.md.txt) populates `target_cpa_scaling_modifier` (instead of `target_cpa_micros`) to show what happens if the campaign target CPA and all ad group target CPAs in the campaign are scaled by that modifier.

For more information, see [Estimate your results with bid, budget, and target
simulators](https://support.google.com/google-ads/answer/2470105).

## Code example: retrieve ad group criterion bid simulations

The following example demonstrates how to retrieve and print all CPC bid
(`CPC_BID`) simulations available for the criteria in a given ad group by
filtering `ad_group_criterion_simulation` on `ad_group_id`.


### Java

```java
private void runExample(GoogleAdsClient googleAdsClient, long customerId, long adGroupId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    // Creates a query that retrieves the ad group criterion CPC bid simulations.
    String query =
        String.format(
            "SELECT ad_group_criterion_simulation.ad_group_id, "
                + "ad_group_criterion_simulation.criterion_id, "
                + "ad_group_criterion_simulation.start_date, "
                + "ad_group_criterion_simulation.end_date, "
                + "ad_group_criterion_simulation.cpc_bid_point_list.points "
                + "FROM ad_group_criterion_simulation "
                + "WHERE ad_group_criterion_simulation.type = CPC_BID "
                + "AND ad_group_criterion_simulation.ad_group_id = %d",
            adGroupId);
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Issues the search stream request.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates over all rows in all messages and prints the requested field values for
    // the ad group criterion CPC bid simulation in each row.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        AdGroupCriterionSimulation simulation = googleAdsRow.getAdGroupCriterionSimulation();
        System.out.printf(
            "Found ad group criterion CPC bid simulation for ad group ID %d, "
                + "criterion ID %d, start date '%s', end date '%s', and points:%n",
            simulation.getAdGroupId(),
            simulation.getCriterionId(),
            simulation.getStartDate(),
            simulation.getEndDate());
        for (CpcBidSimulationPoint point : simulation.getCpcBidPointList().getPointsList()) {
          System.out.printf(
              "  bid: %d => clicks: %d, cost: %d, impressions: %d, "
                  + "biddable conversions: %.2f, biddable conversions value: %.2f%s",
              point.getCpcBidMicros(),
              point.getClicks(),
              point.getCostMicros(),
              point.getImpressions(),
              point.getBiddableConversions(),
              point.getBiddableConversions());
        }
      }
    }
  }
}
      
```

### C#

```c#
public void Run(GoogleAdsClient client, long customerId, long adGroupId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService =
        client.GetService(Services.V26.GoogleAdsService);

    try
    {
        // Creates a query that retrieves the ad group criterion CPC bid simulations.
        string query = $@"
            SELECT
                ad_group_criterion_simulation.ad_group_id,
                ad_group_criterion_simulation.criterion_id,
                ad_group_criterion_simulation.start_date,
                ad_group_criterion_simulation.end_date,
                ad_group_criterion_simulation.cpc_bid_point_list.points
            FROM
                ad_group_criterion_simulation
            WHERE
                ad_group_criterion_simulation.type = CPC_BID AND
                ad_group_criterion_simulation.ad_group_id = {adGroupId}";

        // Issue a search stream request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse response)
            {
                // Iterates over all rows in all messages and prints the requested field
                // values for the ad group criterion CPC bid simulation in each row.
                foreach (GoogleAdsRow googleAdsRow in response.Results)
                {
                    AdGroupCriterionSimulation simulation =
                        googleAdsRow.AdGroupCriterionSimulation;

                    Console.WriteLine("Found ad group criterion CPC bid simulation for " +
                        $"ad group ID {simulation.AdGroupId}, " +
                        $"criterion ID {simulation.CriterionId}, " +
                        $"start date {simulation.StartDate}, " +
                        $"end date {simulation.EndDate}");

                    foreach (CpcBidSimulationPoint point in
                        simulation.CpcBidPointList.Points)
                    {
                        Console.WriteLine($"\tbid: {point.CpcBidMicros} => " +
                            $"clicks: {point.Clicks}, " +
                            $"cost: {point.CostMicros}, " +
                            $"impressions: {point.Impressions}, " +
                            $"biddable conversions: {point.BiddableConversions}, " +
                            "biddable conversions value: " +
                            $"{point.BiddableConversionsValue}");
                    }

                    Console.WriteLine();
                }
            }
        );
    }
      
```

### PHP

```php
public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $adGroupId
) {
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();

    // Creates a query that retrieves the ad group criterion CPC bid simulations.
    $query = sprintf(
        'SELECT ad_group_criterion_simulation.ad_group_id, ' .
        'ad_group_criterion_simulation.criterion_id, ' .
        'ad_group_criterion_simulation.start_date, ' .
        'ad_group_criterion_simulation.end_date, ' .
        'ad_group_criterion_simulation.cpc_bid_point_list.points ' .
        'FROM ad_group_criterion_simulation ' .
        'WHERE ad_group_criterion_simulation.type = CPC_BID ' .
        'AND ad_group_criterion_simulation.ad_group_id = %d',
        $adGroupId
    );

    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the ad group criterion CPC bid simulation in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        $simulation = $googleAdsRow->getAdGroupCriterionSimulation();
        printf(
            'Found ad group criterion CPC bid simulation for ad group ID %d, ' .
            'criterion ID %d, start date "%s", end date "%s", and points:%s',
            $simulation->getAdGroupId(),
            $simulation->getCriterionId(),
            $simulation->getStartDate(),
            $simulation->getEndDate(),
            PHP_EOL
        );
        foreach ($simulation->getCpcBidPointList()->getPoints() as $point) {
            /** @var CpcBidSimulationPoint $point */
            printf(
                '  bid: %d => clicks: %d, cost: %d, impressions: %d, ' .
                'biddable conversions: %.2f, biddable conversions value: %.2f%s',
                $point->getCpcBidMicros(),
                $point->getClicks(),
                $point->getCostMicros(),
                $point->getImpressions(),
                $point->getBiddableConversions(),
                $point->getBiddableConversionsValue(),
                PHP_EOL
            );
        }

        print PHP_EOL;
    }
}
      
```

### Python

```python
def main(client: GoogleAdsClient, customer_id: str, ad_group_id: str):
    googleads_service: GoogleAdsServiceClient = client.get_service(
        "GoogleAdsService"
    )

    query = f"""
        SELECT
          ad_group_criterion_simulation.ad_group_id,
          ad_group_criterion_simulation.criterion_id,
          ad_group_criterion_simulation.start_date,
          ad_group_criterion_simulation.end_date,
          ad_group_criterion_simulation.cpc_bid_point_list.points
        FROM ad_group_criterion_simulation
        WHERE
          ad_group_criterion_simulation.type = CPC_BID
          AND ad_group_criterion_simulation.ad_group_id = {ad_group_id}"""

    # Issues a search request using streaming.
    stream: Iterable[SearchGoogleAdsStreamResponse] = (
        googleads_service.search_stream(customer_id=customer_id, query=query)
    )

    # Iterates over all rows in all messages and prints the requested field
    # values for the ad group criterion CPC bid simulation in each row.
    batch: SearchGoogleAdsStreamResponse
    for batch in stream:
        row: GoogleAdsRow
        for row in batch.results:
            simulation: AdGroupCriterionSimulation = (
                row.ad_group_criterion_simulation
            )

            print(
                "found ad group criterion CPC bid simulation for "
                f"ad group ID {simulation.ad_group_id}, "
                f"criterion ID {simulation.criterion_id}, "
                f"start date {simulation.start_date}, "
                f"end date {simulation.end_date}"
            )

            point: CpcBidSimulationPoint
            for point in simulation.cpc_bid_point_list.points:
                print(
                    f"\tbid: {point.cpc_bid_micros} => "
                    f"clicks: {point.clicks}",
                    f"cost: {point.cost_micros}, "
                    f"impressions: {point.impressions},"
                    "biddable conversions: "
                    f"{point.biddable_conversions},"
                    f"biddable conversions value: "
                    f"{point.biddable_conversions_value}",
                )

            print()
      
```

### Ruby

```ruby
def get_ad_group_criterion_cpc_bid_simulations(customer_id, ad_group_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  query = <<~QUERY
    SELECT ad_group_criterion_simulation.ad_group_id,
           ad_group_criterion_simulation.criterion_id,
           ad_group_criterion_simulation.start_date,
           ad_group_criterion_simulation.end_date,
           ad_group_criterion_simulation.cpc_bid_point_list.points
    FROM ad_group_criterion_simulation
    WHERE ad_group_criterion_simulation.type = CPC_BID 
    AND ad_group_criterion_simulation.ad_group_id = #{ad_group_id}
  QUERY

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: query,
  )

  responses.each do |response|
    response.results.each do |row|
      simulation = row.ad_group_criterion_simulation

      puts "Found ad group criterion CPC bid simulation for " \
      "ad group ID #{simulation.ad_group_id}, " \
      "criterion ID #{simulation.criterion_id}, " \
      "start date '#{simulation.start_date}', " \
      "end date '#{simulation.end_date}', and points:"

      simulation.cpc_bid_point_list.points.each do |point|
        puts "  bid: #{point.cpc_bid_micros} => " \
        "clicks: #{point.clicks}, " \
        "cost: #{point.cost_micros}, " \
        "impressions: #{point.impressions}, " \
        "biddable conversions: #{point.biddable_conversions.round(2)}, " \
        "biddable conversions value: #{point.biddable_conversions_value.round(2)}"
      end
    end
  end
end
      
```

### Perl

```perl
sub get_ad_group_criterion_cpc_bid_simulations {
  my ($api_client, $customer_id, $ad_group_id) = @_;

  # Create a query that retrieves the ad group criterion CPC bid simulations.
  my $search_query =
    "SELECT ad_group_criterion_simulation.ad_group_id, " .
    "ad_group_criterion_simulation.criterion_id, " .
    "ad_group_criterion_simulation.start_date, " .
    "ad_group_criterion_simulation.end_date, " .
    "ad_group_criterion_simulation.cpc_bid_point_list.points " .
    "FROM ad_group_criterion_simulation " .
    "WHERE ad_group_criterion_simulation.type = CPC_BID " .
    "AND ad_group_criterion_simulation.ad_group_id = $ad_group_id";

  my $search_stream_request =
    Google::Ads::GoogleAds::V26::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      => $search_query
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search stream request, iterate over all rows in all messages and
  # print the requested field values for the ad group criterion CPC bid
  # simulation in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      my $simulation     = $google_ads_row->{adGroupCriterionSimulation};

      printf
        "Found ad group criterion CPC bid simulation for ad group ID %d, " .
        "criterion ID %d, start date '%s', end date '%s', and points:\n",
        $simulation->{adGroupId}, $simulation->{criterionId},
        $simulation->{startDate}, $simulation->{endDate};

      foreach my $point (@{$simulation->{cpcBidPointList}{points}}) {
        printf "  bid: %d => clicks: %d, cost: %d, impressions: %d, " .
          "biddable conversions: %.2f, biddable conversions value: %.2f\n",
          $point->{cpcBidMicros},
          $point->{clicks},
          $point->{costMicros},
          $point->{impressions},
          $point->{biddableConversions},
          $point->{biddableConversionsValue};
      }
    });

  return 1;
}
      
```

### curl

> [!NOTE]
> **Note:** While a direct REST code sample for this step isn't provided here, you can achieve this using a manual REST request.   
>
> Refer to the Google Ads API REST interface documentation and the method-specific reference pages. You will need to construct the JSON payload based on the proto definitions.   
>
> Key Resources:
>
> - [Using REST](https://developers.google.com/google-ads/api/rest/overview.md.txt)
> - [REST Interface Structure](https://developers.google.com/google-ads/api/rest/design/overview.md.txt)
> - [JSON Field Mappings](https://developers.google.com/google-ads/api/rest/design/json-mappings.md.txt)
> - Consult the [REST API Reference](https://developers.google.com/google-ads/api/reference/rpc/latest/overview) for the specific service and method.

<br />