{
  "openapi": "3.0.1",
  "info": {
    "title": "Flight Fare History API: book-now / wait from your own history",
    "description": "Book-now or wait, scored against the fare history YOU accumulate in your own key-value store, not a generic average. With no history yet it prices a spread of nearby dates and labels exactly what it could establish: every row names its basis and confidence, or says plainly it has neither.",
    "version": "0.7",
    "x-build-id": "v2HTY5UqF6iNs8rsC"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/frameprobe~flight-fare-history-api/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-frameprobe-flight-fare-history-api",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/frameprobe~flight-fare-history-api/runs": {
      "post": {
        "operationId": "runs-sync-frameprobe-flight-fare-history-api",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/frameprobe~flight-fare-history-api/run-sync": {
      "post": {
        "operationId": "run-sync-frameprobe-flight-fare-history-api",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "origin",
          "destination"
        ],
        "properties": {
          "origin": {
            "title": "Origin airport (IATA)",
            "type": "string",
            "description": "3-letter IATA code, e.g. LAX. Case does not matter."
          },
          "destination": {
            "title": "Destination airport (IATA)",
            "type": "string",
            "description": "3-letter IATA code, e.g. JFK."
          },
          "departDates": {
            "title": "Departure dates to watch",
            "type": "array",
            "description": "YYYY-MM-DD dates. Each one becomes its own price series, because a fare is only comparable with itself. Leave this empty and the Actor watches a single date 60 days out, computed at run time, so a saved input never goes stale. Set dateWindowDays instead to watch a rolling window. Past dates are rejected rather than skipped.",
            "items": {
              "type": "string"
            }
          },
          "dateWindowDays": {
            "title": "Or: watch the next N days",
            "minimum": 1,
            "maximum": 60,
            "type": "integer",
            "description": "Instead of listing dates, watch every departure date from tomorrow to N days out. Each day is a separate upstream search billed to your account, so start small. Maximum 60."
          },
          "returnAfterDays": {
            "title": "Return after N days (round trip)",
            "minimum": 0,
            "maximum": 365,
            "type": "integer",
            "description": "Leave empty for one-way. Set to 7 for a week-long round trip from each departure date."
          },
          "cabinClass": {
            "title": "Cabin class",
            "enum": [
              "economy",
              "premium_economy",
              "business",
              "first"
            ],
            "type": "string",
            "description": "Part of the series identity: economy and business are different products and are never compared with each other.",
            "default": "economy"
          },
          "adults": {
            "title": "Adults",
            "minimum": 1,
            "maximum": 9,
            "type": "integer",
            "description": "Passenger count. Also part of the series identity.",
            "default": 1
          },
          "maxStops": {
            "title": "Maximum stops",
            "minimum": 0,
            "maximum": 3,
            "type": "integer",
            "description": "0 for nonstop only. Leave empty for any. This filters the candidate set, so it changes the minimum price and therefore starts its own series."
          },
          "airlines": {
            "title": "Only these carriers",
            "type": "array",
            "description": "2-character carrier codes, e.g. [\"DL\"]. Leave empty for all carriers. Requires upstreamActor to be a scraper that filters by carrier natively (memo23/google-flights-scraper); the run is refused rather than storing an observation labelled with a filter that was never applied.",
            "items": {
              "type": "string"
            }
          },
          "currency": {
            "title": "Currency",
            "type": "string",
            "description": "3-letter code. A series never mixes currencies: if the upstream returns a different one, today's price is reported and the history is left untouched rather than corrupted.",
            "default": "USD"
          },
          "historyStoreName": {
            "title": "History store name",
            "type": "string",
            "description": "The named key-value store IN YOUR ACCOUNT where the fare series are kept, one record per itinerary. Keep the default to build one history across runs. Change it to keep separate histories side by side. The data is yours: you can read, export or delete it without this Actor.",
            "default": "fare-history"
          },
          "maxItineraries": {
            "title": "Itineraries to consider per date",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many results to read from the upstream search before taking the cheapest. The upstream bills you per result returned, so this is the biggest lever on what a run actually costs. Raising it rarely changes the minimum: on a measured LAX-JFK search, results 10-29 contained nothing cheaper than the fare already found in the first ten.",
            "default": 20
          },
          "routeBaselineDates": {
            "title": "Extra dates to price for a first-run verdict",
            "minimum": 0,
            "maximum": 12,
            "type": "integer",
            "description": "Solves the cold start. On a run whose itineraries have too little stored history to be scored, this many EXTRA departure dates on the same route are priced so today's fare can be placed among the dates you could fly, instead of coming back as INSUFFICIENT_HISTORY. They are spaced in whole weeks around your date, so day of week is held constant. Each one is a separate upstream search billed to your account, exactly like a watched date, and they are NOT charged this Actor's fare-observation event. Spending stops as soon as the run has priced 7 dates in total, which is what a date needs to be scored at medium confidence (a date is never counted in its own baseline). List 7 departDates yourself and this costs nothing; lower it to 4 for a cheaper first run at low confidence. Set to 0 to switch it off and accept INSUFFICIENT_HISTORY until your history fills in.",
            "default": 6
          },
          "upstreamActor": {
            "title": "Upstream flight scraper",
            "type": "string",
            "description": "The Actor run to fetch today's itineraries. Its runs are billed to YOUR Apify account at its own price, separately from this Actor's events. Two are supported directly: automation-lab/google-flights-scraper (the default) and memo23/google-flights-scraper. Field names differ between them and are translated for you. Note that only memo23 can filter by airline, so `airlines` requires it; `maxStops` works with either, applied by this Actor when the upstream cannot. Naming any other scraper sends the memo23 field shape, which you can override with upstreamInput.",
            "default": "automation-lab/google-flights-scraper"
          },
          "datasetId": {
            "title": "Or: score a search you already ran",
            "type": "string",
            "description": "Already have a flight scraper dataset? Point at it and nothing is fetched, so no upstream cost. The rows are scored against your history exactly as a fresh search would be. Route-baseline dates are never bought in this case: you chose to do the fetching, so this Actor spends nothing behind that choice."
          },
          "upstreamInput": {
            "title": "Extra input for the upstream scraper",
            "type": "object",
            "description": "Passed through to the upstream Actor, e.g. proxy settings. Route, dates, cabin and currency are always set by this Actor and cannot be overridden here: a run that searched one itinerary and stored it under another would poison your history."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}