---
updatedAt: 2026-05-06T15:56:27.000Z
agentTools:
  projectIndex: https://dev.kevel.com/llms.txt
---

# Get reserved campaign

Returns a reserved campaign by its ID.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Forecast API",
    "description": "The Kevel Forecast API",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://api.kevel.co/v1"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/forecaster/reserved-campaign/{reservedCampaignId}": {
      "parameters": [
        {
          "name": "reservedCampaignId",
          "in": "path",
          "description": "The reserved campaign ID.",
          "required": true,
          "schema": {
            "type": "integer"
          }
        }
      ],
      "get": {
        "summary": "Get reserved campaign",
        "description": "Returns a reserved campaign by its ID.",
        "tags": [
          "Reserved Campaigns"
        ],
        "responses": {
          "200": {
            "description": "Normal response, containing a JSON object with the reserved campaign, if it exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Update reserved campaign",
        "description": "Fully replace an existing reserved campaign with the provided data.\nAll required fields must be provided.\n\n**Important: ID handling for flights and ads**\n\n- The campaign `id` is required and must match the path parameter.\n- Flights and ads **with an `id`**: Will be updated in-place if the ID exists.\n- Flights and ads **without an `id`**: Will be created as new entities with auto-generated IDs.\n- Existing flights and ads **not included** in the request: Will be **deleted**.\n\nThis means the PUT operation performs a full replacement of the reserved campaign structure.\nTo preserve existing flights or ads, you must include them in the request with their respective IDs.\n",
        "tags": [
          "Reserved Campaigns"
        ],
        "requestBody": {
          "description": "The JSON object with the complete reserved campaign data.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "title": "Reserved Campaign",
                "type": "object",
                "description": "A reserved campaign represents a campaign that is reserved (or booked) for a specific advertiser.\nIt is used to forecast how reserved campaigns will impact future inventory availability.\n",
                "properties": {
                  "id": {
                    "type": "integer",
                    "description": "Unique identifier of the reserved campaign.\nAuto-generated on creation (do not include when creating).\nRequired when updating via PUT.\n",
                    "example": 1234
                  },
                  "name": {
                    "type": "string",
                    "description": "The name of the reserved campaign.",
                    "example": "Holiday Campaign 2025"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "reserved",
                      "booked"
                    ],
                    "default": "reserved",
                    "description": "The status of the campaign:\n  * _reserved_: The campaign is reserved but not yet booked.\n  * _booked_: The campaign has been confirmed and booked so it will not be considered as a reservation in the forecasts.\n"
                  },
                  "description": {
                    "type": "string",
                    "nullable": true,
                    "description": "An optional description of the reserved campaign.",
                    "example": "Premium holiday campaign for Q4"
                  },
                  "salesProbabilityWeight": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "A weight (0-100) representing the probability that this reserved campaign will convert to a booked campaign.\n",
                    "example": 75
                  },
                  "advertiser": {
                    "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/advertiser"
                  },
                  "capType": {
                    "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/capType"
                  },
                  "dailyCapAmount": {
                    "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/dailyCapAmount"
                  },
                  "lifetimeCapAmount": {
                    "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/lifetimeCapAmount"
                  },
                  "frequencyCap": {
                    "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/frequencyCap"
                  },
                  "flights": {
                    "type": "array",
                    "minItems": 1,
                    "description": "The flights associated with this reserved campaign. At least one flight is required.\n",
                    "items": {
                      "title": "Reserved Flight",
                      "type": "object",
                      "description": "A flight within a reserved campaign.\n",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "description": "Unique identifier of the flight.\nAuto-generated on creation (do not include when creating).\nWhen updating via PUT: include to update in-place, omit to create as new.\n",
                          "example": 5678
                        },
                        "priorityId": {
                          "type": "integer",
                          "description": "The ID of the priority level for this flight.",
                          "example": 221170
                        },
                        "rate": {
                          "title": "Rate",
                          "type": "object",
                          "description": "The rate configuration for billing.",
                          "properties": {
                            "rateType": {
                              "type": "integer",
                              "enum": [
                                1,
                                2,
                                3,
                                4,
                                5,
                                6
                              ],
                              "description": "The type of rate:\n  * _1_: Flat\n  * _2_: CPM (Cost Per Mille/Thousand Impressions)\n  * _3_: CPC (Cost Per Click)\n  * _4_: CPA View (Cost Per Action - View)\n  * _5_: CPA Click (Cost Per Action - Click)\n  * _6_: CPA Both (Cost Per Action - Both)\n",
                              "example": 2
                            },
                            "price": {
                              "type": "number",
                              "description": "The price amount for the rate.",
                              "example": 5.5
                            }
                          },
                          "required": [
                            "rateType",
                            "price"
                          ]
                        },
                        "keywordTargeting": {
                          "type": "string",
                          "nullable": true,
                          "description": "Keyword targeting rules. Please head to [Keyword Logic](doc:keyword-logic) for more details.\n",
                          "example": "keyword1,keyword2\nkeyword3\n!keyword1,keyword2"
                        },
                        "siteZoneTargeting": {
                          "type": "array",
                          "nullable": true,
                          "items": {
                            "title": "Site Zone Targeting",
                            "type": "object",
                            "description": "Site and zone targeting rules. Please head to [Site/Zone Targeting](ref:create-sitezone-targeting) for more details.\n",
                            "properties": {
                              "SiteId": {
                                "type": "integer",
                                "example": 1121285
                              },
                              "ZoneId": {
                                "type": "integer",
                                "example": 247884
                              },
                              "IsExclude": {
                                "type": "boolean"
                              }
                            },
                            "anyOf": [
                              {
                                "required": [
                                  "SiteId"
                                ]
                              },
                              {
                                "required": [
                                  "ZoneId"
                                ]
                              }
                            ]
                          }
                        },
                        "geoTargeting": {
                          "type": "array",
                          "nullable": true,
                          "items": {
                            "title": "Geo Targeting",
                            "type": "object",
                            "description": "Geographic targeting rules. Please head to [Geo Targeting](ref:create-geo-targeting) for more details.\n",
                            "properties": {
                              "CountryCode": {
                                "type": "string",
                                "description": "The two-character country code.",
                                "example": "US"
                              },
                              "Region": {
                                "type": "string",
                                "description": "The two-character code for the state, region, or province.",
                                "example": "NY"
                              },
                              "MetroCode": {
                                "type": "string",
                                "description": "The metro code, such as ZIP code.",
                                "example": "10001"
                              },
                              "CityGeonameId": {
                                "type": "integer",
                                "description": "The numeric GeoNames ID for city-level targeting. This value is used for matching, not the city name. Please head to [Geo Targeting](ref:create-geo-targeting) for more details.",
                                "example": 5128581
                              },
                              "IsExclude": {
                                "type": "boolean",
                                "description": "Set to 'false' (default) to target; 'true' to exclude."
                              }
                            },
                            "required": [
                              "CountryCode"
                            ]
                          }
                        },
                        "distanceTargeting": {
                          "type": "array",
                          "nullable": true,
                          "items": {
                            "title": "Distance Targeting",
                            "type": "object",
                            "description": "Distance-based geographic targeting. Please head to [Distance Targeting](ref:create-geodistance-targeting-geometry) for more details.\n",
                            "properties": {
                              "distance": {
                                "type": "number",
                                "description": "The radius distance in kilometers.",
                                "example": 20
                              },
                              "latitude": {
                                "type": "number",
                                "description": "The latitude of the center point.",
                                "example": 41.40338
                              },
                              "longitude": {
                                "type": "number",
                                "description": "The longitude of the center point.",
                                "example": 2.17403
                              }
                            },
                            "required": [
                              "distance",
                              "latitude",
                              "longitude"
                            ]
                          }
                        },
                        "customTargeting": {
                          "type": "string",
                          "nullable": true,
                          "description": "A string for custom targeting using the [Zerkel Language](doc:zerkel-queries).\n",
                          "example": "[\"order_confirmation\"] contains screen"
                        },
                        "duplicateMode": {
                          "title": "Duplicate Mode",
                          "type": "integer",
                          "nullable": true,
                          "enum": [
                            1,
                            2,
                            3,
                            4
                          ],
                          "description": "When defined, enables no duplicates and defines the type of the duplicate mode:\n  * _1_: Flight\n  * _2_: Campaign\n  * _3_: Advertiser\n  * _4_: Creative\n"
                        },
                        "ads": {
                          "type": "array",
                          "minItems": 1,
                          "description": "The ads associated with this flight. At least one ad is required.\n",
                          "items": {
                            "title": "Reserved Ad",
                            "type": "object",
                            "description": "An ad within a reserved flight.",
                            "properties": {
                              "id": {
                                "type": "integer",
                                "description": "Unique identifier of the ad.\nAuto-generated on creation (do not include when creating).\nWhen updating via PUT: include to update in-place, omit to create as new.\n",
                                "example": 9012
                              },
                              "adType": {
                                "type": "integer",
                                "description": "The ad type ID.",
                                "example": 4649
                              }
                            },
                            "required": [
                              "adType"
                            ]
                          }
                        },
                        "segmentTargeting": {
                          "type": "array",
                          "nullable": true,
                          "description": "Segment-based audience targeting.",
                          "items": {
                            "title": "Segment Targeting",
                            "type": "object",
                            "description": "Audience segment targeting configuration.",
                            "properties": {
                              "segmentId": {
                                "type": "integer",
                                "description": "The ID of the audience segment to target.",
                                "example": 12345
                              },
                              "isExclude": {
                                "type": "boolean",
                                "default": false,
                                "description": "Whether to exclude (true) or include (false) users in this segment."
                              },
                              "category": {
                                "type": "string",
                                "example": "Demographics",
                                "description": "The category the segment belongs to. Include segments are matched OR-within-category and AND-across-categories: a request must match at least one included segment in every targeted category. Optional; segments with no category are treated as a single uncategorized group, so all-one-category (or no category) reduces to the flat OR behavior. Ignored for excluded segments, because exclude is a flat deny."
                              }
                            },
                            "required": [
                              "segmentId"
                            ]
                          }
                        },
                        "categoryTargeting": {
                          "type": "array",
                          "nullable": true,
                          "items": {
                            "title": "Category Targeting",
                            "type": "object",
                            "description": "Category targeting compares outer-trimmed whole values case-insensitively, preserving internal whitespace.\nIDs retain their trimmed casing and must be non-empty, well-formed UTF-16 with at most 200 UTF-16 code units.\nDuplicate lowercase comparison keys are rejected across include and exclude rules.\nPlease head to [Category Targeting](doc:category) for more details.\n",
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The category ID or breadcrumb-style path such as `\"Electricals > Computing > Laptops\"` used in the Decision API placement.",
                                "example": "Electricals > Computing"
                              },
                              "isExclude": {
                                "type": "boolean",
                                "description": "Whether to exclude (`true`) or include (`false`) requests that match this rule."
                              }
                            },
                            "required": [
                              "id",
                              "isExclude"
                            ]
                          },
                          "description": "Category targeting rules. Please head to [Category Targeting](doc:category) for more details."
                        },
                        "startDate": {
                          "type": "string",
                          "format": "date-time",
                          "description": "The start date and time of the flight.",
                          "example": "2025-01-01T00:00:00.000"
                        },
                        "endDate": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "The end date and time of the flight. Required for goal types other than Percentage (2), Daily Revenue (9), or Monthly Revenue (10).\nMust be after the start date and after the current date.\n",
                          "example": "2025-03-31T23:59:59.000"
                        },
                        "timeZone": {
                          "type": "string",
                          "default": "UTC",
                          "description": "The time zone for the flight's schedule.",
                          "example": "America/New_York"
                        },
                        "goalType": {
                          "type": "integer",
                          "enum": [
                            1,
                            2,
                            3,
                            7,
                            8,
                            9,
                            10
                          ],
                          "description": "The type of goal for this flight:\n  * _1_: Impressions\n  * _2_: Percentage\n  * _3_: Clicks\n  * _7_: Conversions\n  * _8_: Revenue\n  * _9_: Daily Revenue\n  * _10_: Monthly Revenue\n",
                          "example": 1
                        },
                        "goalAmount": {
                          "type": "integer",
                          "description": "The target amount for the goal (e.g., number of impressions, percentage, etc.).",
                          "example": 1000000
                        },
                        "capType": {
                          "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/capType"
                        },
                        "dailyCapAmount": {
                          "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/dailyCapAmount"
                        },
                        "lifetimeCapAmount": {
                          "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/lifetimeCapAmount"
                        },
                        "frequencyCap": {
                          "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/frequencyCap"
                        },
                        "searchTerms": {
                          "type": "array",
                          "nullable": true,
                          "description": "Search term targeting rules. Please head to [Search Term Targeting](doc:search-term-targeting) for more details.\n",
                          "items": {
                            "title": "Search Term Targeting",
                            "type": "object",
                            "description": "Search term targeting rule. Please head to [Search Term Targeting](doc:search-term-targeting) for more details.\n",
                            "properties": {
                              "term": {
                                "type": "string",
                                "description": "The search term to match against.",
                                "example": "running shoes"
                              },
                              "matchType": {
                                "type": "string",
                                "enum": [
                                  "broad",
                                  "strict",
                                  "exact"
                                ],
                                "description": "How `term` is matched against the ad request's search term.",
                                "example": "broad"
                              },
                              "isExclude": {
                                "type": "boolean",
                                "default": false,
                                "description": "Whether to exclude (`true`) or include (`false`) requests that match this rule."
                              }
                            },
                            "required": [
                              "term",
                              "matchType"
                            ]
                          }
                        },
                        "bidModifiers": {
                          "type": "array",
                          "nullable": true,
                          "description": "Bid modifiers to apply to the flight's effective price for matching ad requests.\nPlease head to [Bid Modifiers](doc:bid-modifiers) for more details.\n",
                          "items": {
                            "title": "Bid Modifier",
                            "type": "object",
                            "description": "A bid modifier that adjusts a flight's effective price for ad requests matching the given conditions.\nPlease head to [Bid Modifiers](doc:bid-modifiers) for more details.\n",
                            "properties": {
                              "match": {
                                "type": "object",
                                "description": "The match conditions for the bid modifier.",
                                "properties": {
                                  "Keyword": {
                                    "type": "string"
                                  },
                                  "Site": {
                                    "type": "integer",
                                    "format": "int32"
                                  },
                                  "Zone": {
                                    "type": "integer",
                                    "format": "int32"
                                  },
                                  "Segment": {
                                    "type": "integer",
                                    "format": "int32"
                                  },
                                  "SearchTerm": {
                                    "type": "object",
                                    "properties": {
                                      "Term": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "Category": {
                                    "type": "object",
                                    "properties": {
                                      "Id": {
                                        "type": "string"
                                      }
                                    },
                                    "required": [
                                      "Id"
                                    ]
                                  }
                                }
                              },
                              "price": {
                                "type": "number",
                                "nullable": true,
                                "description": "Fixed effective price to use when this modifier applies. Takes precedence over `multiplier`\nwhen both are set.\n",
                                "example": 7.5
                              },
                              "multiplier": {
                                "type": "number",
                                "nullable": true,
                                "description": "Factor applied to the flight's price when this modifier applies. Ignored if `price` is set.\n",
                                "example": 1.5
                              }
                            },
                            "required": [
                              "match"
                            ]
                          }
                        },
                        "isCompanion": {
                          "type": "boolean",
                          "nullable": true,
                          "default": false,
                          "description": "Marks a companion flight. When true, the flight's ads are treated as companion ads: when one wins a placement,\nthe forecast co-allocates the flight's other ads across the request's remaining placements.\n",
                          "example": false
                        }
                      },
                      "required": [
                        "priorityId",
                        "rate",
                        "ads",
                        "startDate",
                        "goalType",
                        "goalAmount"
                      ]
                    }
                  }
                },
                "required": [
                  "name",
                  "salesProbabilityWeight",
                  "advertiser",
                  "flights"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normal response, containing the updated JSON object with the reserved campaign, if successful.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidBody"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "summary": "Patch reserved campaign",
        "description": "Partially update one or more fields of a reserved campaign.\nOnly the provided fields will be updated; other fields remain unchanged.\nNote: Array fields (like flights) are not supported in patch operations.\n",
        "tags": [
          "Reserved Campaigns"
        ],
        "requestBody": {
          "description": "A JSON object with one or more of the reserved campaign fields to update.",
          "content": {
            "application/json": {
              "schema": {
                "title": "Patchable Reserved Campaign",
                "type": "object",
                "description": "Schema for partially updating a reserved campaign. All fields are optional. Only the provided fields will be updated, other fields remain unchanged.",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The name of the reserved campaign."
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "reserved",
                      "booked"
                    ],
                    "description": "The status of the campaign."
                  },
                  "description": {
                    "type": "string",
                    "nullable": true,
                    "description": "An optional description of the reserved campaign."
                  },
                  "salesProbabilityWeight": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "A weight (0-100) representing the probability that this reserved campaign will convert to a booked campaign."
                  },
                  "advertiser": {
                    "title": "Advertiser",
                    "type": "object",
                    "description": "The advertiser associated with the reserved campaign.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "The unique identifier of the advertiser. Must be an existing advertiser.",
                        "example": 10
                      },
                      "frequencyCap": {
                        "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/frequencyCap"
                      },
                      "placementLimit": {
                        "type": "integer",
                        "nullable": true,
                        "description": "Maximum number of placements for this advertiser."
                      },
                      "caps": {
                        "type": "object",
                        "nullable": true,
                        "description": "Ad caps for the advertiser."
                      }
                    },
                    "required": [
                      "id"
                    ]
                  },
                  "capType": {
                    "title": "Cap Type",
                    "type": "integer",
                    "nullable": true,
                    "enum": [
                      1,
                      2,
                      3,
                      4
                    ],
                    "description": "The type of cap:\n  * _1_: Impressions\n  * _2_: Clicks\n  * _3_: Conversions\n  * _4_: Revenue\n"
                  },
                  "dailyCapAmount": {
                    "title": "Daily Cap Amount",
                    "type": "integer",
                    "nullable": true,
                    "description": "The daily cap amount (based on capType).",
                    "example": 10000
                  },
                  "lifetimeCapAmount": {
                    "title": "Lifetime Cap Amount",
                    "type": "integer",
                    "nullable": true,
                    "description": "The lifetime cap amount (based on capType).",
                    "example": 1000000
                  },
                  "frequencyCap": {
                    "title": "Frequency Cap",
                    "type": "object",
                    "nullable": true,
                    "description": "Configuration for limiting ad frequency to users.",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "enum": [
                          1,
                          2,
                          3
                        ],
                        "description": "The time unit for the frequency cap:\n  * _1_: Hour\n  * _2_: Day\n  * _3_: Minute\n",
                        "example": 2
                      },
                      "duration": {
                        "type": "integer",
                        "description": "The number of time units for the cap period.",
                        "example": 1
                      },
                      "value": {
                        "type": "integer",
                        "description": "The maximum number of impressions allowed within the duration.",
                        "example": 5
                      }
                    },
                    "required": [
                      "type",
                      "duration",
                      "value"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normal response, containing the full updated JSON object with the reserved campaign, if successful.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidBody"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Adzerk-ApiKey"
      }
    },
    "responses": {
      "NotFound": {
        "description": "The entity doesn't exist.",
        "content": {
          "text/plain": {
            "schema": {
              "type": "string"
            },
            "example": "Traffic modifier with ID 123 doesn't exist"
          }
        }
      }
    }
  }
}
```