Save a listing search for the signed-in user. Aura Historia matches new listings against it in the background and, with notifications on (the default), notifies the user, so matches appear later. Subscription tier limits apply. Each call creates a new saved search, so repeating a call that timed out can create a duplicate. Each result's `viewLink.url` is the provider link meant to be shared with people: it carries Aura Historia's referral tagging, which is lost when its query parameters are changed. `viewLink.affiliate` is `true` when that link is an affiliate link, which can earn Aura Historia a commission. `url` is the provider's untagged address. Amounts are always integers in the currency's minor unit when one exists (EUR `119199` = €1,191.99; USD in cents). For currencies without minor units, such as JPY, the amount is whole units (`211453` = ¥211,453). Follow ISO 4217 exponents.
View input schema
{
"type": "object",
"properties": {
"acceptShippingDestination": {
"anyOf": [
{
"$ref": "#/$defs/AcceptShippingDestinationData"
},
{
"type": "null"
}
],
"description": "Optional guard confirming the shipping destination: the filter's shipping country must equal the country of the referenced address or browsing preference."
},
"name": {
"description": "Name of the saved search, at most 255 characters (longer names are cut off).",
"type": "string"
},
"notifications": {
"default": true,
"description": "Whether matches trigger notifications (default true).",
"type": "boolean"
},
"search": {
"$ref": "#/$defs/ProductListingSearchData",
"description": "Criteria a listing must meet to match this saved search; the members are those of the listing search.",
"type": "object"
}
},
"required": [
"name",
"search"
],
"$defs": {
"AcceptShippingDestinationData": {
"description": "Optional acceptance guard. The submitted country must equal the authorized address or\npreference's asserted country. Neither the reference nor provider evidence is retained.",
"oneOf": [
{
"additionalProperties": false,
"description": "Compare with the country of one of the user's saved addresses.",
"properties": {
"addressId": {
"description": "ID of the saved address (`uaddr_…`).",
"pattern": "^uaddr_[0-7][0-9a-hjkmnp-tv-z]{9}[ef][0-9a-hjkmnp-tv-z]{2}[89abrstv][0-9a-hjkmnp-tv-z]{12}$",
"type": "string"
},
"kind": {
"const": "ADDRESS",
"description": "Selects this variant; always `ADDRESS` here.",
"type": "string"
}
},
"required": [
"kind",
"addressId"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Compare with the country of the user's stored browsing destination.",
"properties": {
"kind": {
"const": "PREFERENCE",
"description": "Selects this variant; always `PREFERENCE` here.",
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
}
]
},
"AmountData": {
"additionalProperties": false,
"properties": {
"amount": {
"description": "Amount as an integer in the currency's minor unit (EUR cents; JPY whole yen).",
"format": "uint64",
"maximum": 9223372036854776000,
"minimum": 0,
"type": "integer"
},
"currency": {
"description": "ISO 4217 code of the currency the amount is in.",
"enum": [
"EUR",
"GBP",
"USD",
"AUD",
"CAD",
"NZD",
"CNY",
"BRL",
"PLN",
"TRY",
"JPY",
"CZK",
"RUB",
"AED",
"SAR",
"HKD",
"SGD",
"CHF",
"ZAR",
"SEK",
"DKK",
"NOK",
"KRW",
"INR",
"TWD",
"HUF",
"RON",
"MXN",
"THB",
"ARS"
],
"type": "string"
}
},
"required": [
"amount",
"currency"
],
"type": "object"
},
"DateRangeSchema": {
"properties": {
"max": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "End of the range, as an ISO 8601 date-time with offset."
},
"min": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Start of the range, as an ISO 8601 date-time with offset."
}
},
"type": "object"
},
"DestinationData": {
"oneOf": [
{
"additionalProperties": false,
"description": "No destination country.",
"properties": {
"kind": {
"const": "NONE",
"description": "Selects this variant; always `NONE` here.",
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "A destination country.",
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"type": "string"
},
"kind": {
"const": "COUNTRY",
"description": "Selects this variant; always `COUNTRY` here.",
"type": "string"
}
},
"required": [
"kind",
"country"
],
"type": "object"
}
]
},
"GeographicSearchData": {
"additionalProperties": false,
"properties": {
"countries": {
"description": "ISO 3166-1 alpha-2 country codes, at most 100; a listing matches when it is located in any of them.",
"items": {
"type": "string"
},
"type": "array"
},
"distanceOrder": {
"description": "Order results by distance from `origin`, `ASC` (nearest first) or `DESC`; requires `origin`.",
"type": [
"string",
"null"
]
},
"mode": {
"description": "Which locations count when measuring distance: `STRICT` (default) only exact premises, `APPROXIMATE` also street, locality and representative points; `APPROXIMATE` needs `origin` with `radius` or `distanceOrder`.",
"type": [
"string",
"null"
]
},
"origin": {
"anyOf": [
{
"$ref": "#/$defs/OriginData"
},
{
"type": "null"
}
],
"description": "Point that `radius` and `distanceOrder` measure from; required by either of them."
},
"radius": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"amount": {
"description": "Distance in `unit`; greater than 0.",
"type": "number"
},
"unit": {
"description": "Unit of `amount`: one of MILES, YARDS, FEET, INCHES, KILOMETERS, METERS, CENTIMETERS, MILLIMETERS, NAUTICAL_MILES.",
"type": "string"
}
},
"required": [
"amount",
"unit"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Only listings within this distance of `origin`, at most 20,000 km."
},
"subdivisions": {
"description": "ISO 3166-2 subdivision codes, at most 100, that belong to `countries` when those are given; a listing matches when it is located in any of them.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"NumberRangeSchema": {
"properties": {
"max": {
"description": "Highest price to include, as an integer amount in the currency's minor unit.",
"format": "uint64",
"maximum": 18446744073709552000,
"minimum": 0,
"type": [
"integer",
"null"
]
},
"min": {
"description": "Lowest price to include, as an integer amount in the currency's minor unit.",
"format": "uint64",
"maximum": 18446744073709552000,
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"type": "object"
},
"OriginData": {
"additionalProperties": false,
"properties": {
"latitude": {
"description": "Latitude in decimal degrees.",
"format": "double",
"type": "number"
},
"longitude": {
"description": "Longitude in decimal degrees.",
"format": "double",
"type": "number"
}
},
"required": [
"latitude",
"longitude"
],
"type": "object"
},
"ProductListingSearchData": {
"properties": {
"auctionId": {
"description": "Only listings that belong to these auctions, given as auction IDs (`auc_…`).",
"items": {
"pattern": "^auc_[0-7][0-9a-hjkmnp-tv-z]{9}[ef][0-9a-hjkmnp-tv-z]{2}[89abrstv][0-9a-hjkmnp-tv-z]{12}$",
"type": "string"
},
"type": "array"
},
"availability": {
"anyOf": [
{
"items": {
"enum": [
"AVAILABLE",
"IN_STOCK",
"LIMITED_AVAILABILITY",
"BACK_ORDER",
"MADE_TO_ORDER",
"PRE_ORDER",
"PRE_SALE",
"UNAVAILABLE",
"RESERVED",
"OUT_OF_STOCK",
"SOLD_OUT"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Only listings in one of these exact availability states; combined with `orderability`, a listing must satisfy both."
},
"created": {
"$ref": "#/$defs/DateRangeSchema",
"description": "Range on the listing's creation time, as ISO 8601 date-times with offset; both bounds inclusive."
},
"currency": {
"default": "EUR",
"description": "Currency prices are returned in and `price` is interpreted in, as an ISO 4217 code (default `EUR`).",
"enum": [
"EUR",
"GBP",
"USD",
"AUD",
"CAD",
"NZD",
"CNY",
"BRL",
"PLN",
"TRY",
"JPY",
"CZK",
"RUB",
"AED",
"SAR",
"HKD",
"SGD",
"CHF",
"ZAR",
"SEK",
"DKK",
"NOK",
"KRW",
"INR",
"TWD",
"HUF",
"RON",
"MXN",
"THB",
"ARS"
],
"type": "string"
},
"enhancedSearchDescription": {
"description": "Optional natural-language description that refines the ranking of `productQuery` results. Only effective together with `productQuery`; on its own it returns unranked, unrelated results.",
"type": [
"string",
"null"
]
},
"excludeListingSourceId": {
"description": "Leave out listings from these providers, given as listing source IDs (`ls_…`).",
"items": {
"pattern": "^ls_[0-7][0-9a-hjkmnp-tv-z]{9}[ef][0-9a-hjkmnp-tv-z]{2}[89abrstv][0-9a-hjkmnp-tv-z]{12}$",
"type": "string"
},
"type": "array"
},
"excludeProductListingId": {
"description": "Listing IDs (`pl_…`) to leave out of the results.",
"items": {
"pattern": "^pl_[0-7][0-9a-hjkmnp-tv-z]{9}[ef][0-9a-hjkmnp-tv-z]{2}[89abrstv][0-9a-hjkmnp-tv-z]{12}$",
"type": "string"
},
"type": "array"
},
"geography": {
"anyOf": [
{
"$ref": "#/$defs/GeographicSearchData"
},
{
"type": "null"
}
],
"description": "Where listings are located, by country, subdivision or distance from a point; every member given must hold."
},
"includeUnspecifiedAvailability": {
"description": "Also include listings that state no availability (default false).",
"type": [
"boolean",
"null"
]
},
"language": {
"default": "en",
"description": "Language of the returned listing text and of the titles `productQuery` is matched against, as an ISO 639-1 code (default `en`).",
"enum": [
"de",
"en",
"fr",
"es",
"it",
"zh",
"pt",
"pl",
"tr",
"nl",
"cs",
"ja",
"ru",
"ar",
"ko",
"el",
"he",
"th",
"hi",
"de-DE",
"de-AT",
"de-CH",
"de-LU",
"de-LI",
"en-US",
"en-GB",
"en-AU",
"en-CA",
"en-NZ",
"en_IE",
"fr-FR",
"fr-CA",
"fr-BE",
"fr-CH",
"fr-LU",
"es-ES",
"es-MX",
"es-AR",
"es-CO",
"es-CL",
"es-PE",
"es-VE",
"it-IT",
"it-CH",
"zh-CN",
"zh-Hans",
"zh-TW",
"zh-Hant",
"zh-HK",
"pt-PT",
"pt-BR",
"pl-PL",
"tr-TR",
"nl-NL",
"nl-BE",
"cs-CZ",
"ja-JP",
"ru-RU",
"ar-SA",
"ar-EG",
"ar-AE",
"ko-KR",
"el-GR",
"he-IL",
"th-TH",
"hi-IN"
],
"type": "string"
},
"listingSourceId": {
"description": "Only listings from these providers, given as listing source IDs (`ls_…`).",
"items": {
"pattern": "^ls_[0-7][0-9a-hjkmnp-tv-z]{9}[ef][0-9a-hjkmnp-tv-z]{2}[89abrstv][0-9a-hjkmnp-tv-z]{12}$",
"type": "string"
},
"type": "array"
},
"lotBiddingOpens": {
"$ref": "#/$defs/DateRangeSchema",
"description": "Range on the time bidding on the lot opens, as ISO 8601 date-times with offset; `min` inclusive, `max` exclusive."
},
"lotScheduledCloses": {
"$ref": "#/$defs/DateRangeSchema",
"description": "Range on the lot's scheduled closing time, as ISO 8601 date-times with offset; `min` inclusive, `max` exclusive."
},
"orderability": {
"anyOf": [
{
"items": {
"enum": [
"ORDERABLE_NOW",
"ORDERABLE_CONDITIONALLY",
"NOT_ORDERABLE"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Only listings whose availability falls into one of these orderability groups; combined with `availability`, a listing must satisfy both."
},
"price": {
"anyOf": [
{
"$ref": "#/$defs/NumberRangeSchema"
},
{
"type": "null"
}
],
"description": "Price range in the request's `currency`, with both bounds inclusive. Amounts are always integers in the currency's minor unit when one exists (EUR `119199` = €1,191.99; USD in cents). For currencies without minor units, such as JPY, the amount is whole units (`211453` = ¥211,453). Follow ISO 4217 exponents."
},
"productQuery": {
"description": "Keyword phrases matched against listing titles; every word of one phrase must match, and a listing matches when any phrase does.",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
},
"shipping": {
"anyOf": [
{
"$ref": "#/$defs/ShippingSearchData"
},
{
"type": "null"
}
],
"description": "Only listings whose advertised shipping terms meet these conditions for a destination country; every member given must hold."
},
"updated": {
"$ref": "#/$defs/DateRangeSchema",
"description": "Range on the listing's last update time, as ISO 8601 date-times with offset; both bounds inclusive."
}
},
"type": "object"
},
"ShippingSearchData": {
"additionalProperties": false,
"properties": {
"collectionOffered": {
"description": "Only listings that offer collection in person; the only shipping condition that works without a destination country.",
"type": "boolean"
},
"destination": {
"anyOf": [
{
"$ref": "#/$defs/DestinationData"
},
{
"type": "null"
}
],
"description": "Country the listing must ship to, as `{\"kind\":\"COUNTRY\",\"country\":\"DE\"}`; `{\"kind\":\"NONE\"}` sets no destination."
},
"interpretation": {
"description": "`WHOLE_COUNTRY_PER_ITEM_V1` (default) or `WHOLE_COUNTRY_PER_ITEM_FX_V1`, which values `maximumPerItem` in its own currency at the request's exchange rates and requires `maximumPerItem`.",
"type": [
"string",
"null"
]
},
"maximumPerItem": {
"anyOf": [
{
"$ref": "#/$defs/AmountData"
},
{
"type": "null"
}
],
"description": "Highest acceptable shipping price per item, in the amount's own currency; requires a `destination` country. Amounts are always integers in the currency's minor unit when one exists (EUR `119199` = €1,191.99; USD in cents). For currencies without minor units, such as JPY, the amount is whole units (`211453` = ¥211,453). Follow ISO 4217 exponents."
},
"referenceRelease": {
"description": "Version of the ISO 3166 code list the country code comes from; `iso-codes-4.20.1` is the only accepted value and the default.",
"type": [
"string",
"null"
]
},
"service": {
"description": "Shipping service code the terms must include, as free text of at most 128 characters; requires a `destination` country.",
"type": [
"string",
"null"
]
}
},
"type": "object"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"title": "CreateArguments"
}