Search the Metropolitan Museum of Art collection by keyword and optional filters. Returns the total match count and one page of matching object IDs, which met_get_object resolves to full records. Relevance is keyword-based, not semantic; department and geographic filters narrow results more than a longer query. Paging reaches only the first 10,000 matches of any search, so narrow a larger one with filters. The medium parameter takes one object type as the Met spells it ("Paintings", "Sculpture"), not a material like "Oil on canvas". hasImages also includes copyrighted works; CC0 status is per object, from the isPublicDomain and hasCC0Image fields on met_get_object. isHighlight accepts true only. isOnView restricts results to works currently on display in a Met gallery.
View input schema
{
"type": "object",
"properties": {
"q": {
"type": "string",
"minLength": 1,
"description": "Keyword query, matched across title, artist name, culture, medium, tags, and other text fields; matchField narrows the match to titles, tags, or artists and cultures. Broad terms return large ID sets. \"*\" matches every object, for a search narrowed by filters alone; paging still reaches only the first 10,000 matches. An accession number (e.g., \"29.100.5\") ranks its object first, with near-numbered objects after it — confirm the match from accessionNumber on met_get_object."
},
"matchField": {
"description": "Restrict the keyword match to one field: \"title\" matches object titles only, \"tags\" matches subject tags only, \"artistOrCulture\" matches the artist an object is attributed to (artistDisplayName on met_get_object) or its culture. A qualified attribution such as \"Style of\" matches too, so read artistPrefix on met_get_object; another person on the record, such as a sitter, does not. Omit it to match across all text fields. Combines with every filter. Has no effect when q is \"*\".",
"type": "string",
"enum": [
"title",
"tags",
"artistOrCulture"
]
},
"hasImages": {
"description": "When true, restricts results to objects that have at least one associated image, including copyrighted works whose images cannot be reproduced; false restricts them to objects with none. For freely reusable CC0 images, confirm per object from the isPublicDomain and hasCC0Image fields on met_get_object.",
"type": "boolean"
},
"isHighlight": {
"description": "Opt-in filter, true only — omit it rather than passing false, which the search ignores. Selects objects the Met has designated as highlights — major works central to the collection.",
"type": "boolean",
"const": true
},
"isOnView": {
"description": "When true, restricts results to objects currently on display in a Met gallery; false restricts them to objects not on view. The GalleryNumber field on the met_get_object record identifies the specific gallery.",
"type": "boolean"
},
"medium": {
"description": "Filter by one object type, case-sensitive and spelled as the Met spells it (e.g., \"Paintings\", \"Drawings\", \"Prints\", \"Ceramics\", \"Sculpture\", \"Photographs\", \"Textiles\", \"Watercolors\") — \"paintings\" matches nothing. A material description like \"Oil on canvas\" matches nothing either, and neither does a \"|\"-joined list (\"Prints|Paintings\"). The filter is the evidence for a match: a matching object's classification on met_get_object can be empty or name another type, and one object can match several values, so counts split by medium can double-count.",
"type": "string"
},
"departmentId": {
"description": "Restrict results to one curatorial department. Valid IDs come from met_list_departments — the Met exposes a sparse set (roughly 1–21, with gaps); an unrecognized ID is rejected with an invalid_department error rather than silently widening the search. Can be combined with other filters. The Met searches 7 (The Cloisters) and 17 (Medieval Art) as one combined result set: for either, objectIDs keeps only the requested department's matches while total and paging count both, so a page can hold fewer than limit IDs while more remain.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"geoLocation": {
"description": "Filter by geographic origin: one place, whole and case-sensitive as the Met spells it, as a one-element array (e.g., [\"Greece\"], [\"Japan\"]). A different case (\"greece\"), a fragment (\"Gree\"), or a \"|\"-joined list matches nothing, and an adjective such as \"Japanese\" matches nothing either. A matching record may show the place in none of its fields.",
"maxItems": 1,
"type": "array",
"items": {
"type": "string",
"description": "One place, spelled and capitalized as the Met spells it (e.g., \"Greece\")."
}
},
"dateBegin": {
"description": "First year of the date window, inclusive. Negative integers for BCE (e.g., -500 for 500 BCE). Requires dateEnd. The window keeps only objects whose whole date span (objectBeginDate to objectEndDate on met_get_object) lies inside it, so a span crossing either bound is excluded: a \"ca.\" date can be stored as a 20-year span, so widen the window around a displayed year. A window spanning year 0 also matches undated records, whose dates read null on met_get_object.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"dateEnd": {
"description": "Last year of the date window, inclusive. Negative integers for BCE. Requires dateBegin. The window keeps only objects whose whole date span (objectBeginDate to objectEndDate on met_get_object) lies inside it, so a span crossing either bound is excluded: a \"ca.\" date can be stored as a 20-year span. A window spanning year 0 also matches undated records, whose dates read null on met_get_object.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"limit": {
"default": 20,
"description": "Maximum number of object IDs to return in this page. A page holds at most 500 IDs, the Met search maximum: a larger value reads a 500-ID page and the notice says so — continue from nextOffset. Paging reaches only the first 10,000 matches, so a page that would cross 10,000 is cut short there.",
"type": "integer",
"minimum": 1
},
"offset": {
"default": 0,
"description": "Zero-based index of the first match to return (default 0); pass the nextOffset from a previous response to continue paging. Only the first 10,000 matches are reachable, so an offset at or beyond 10,000, or at or beyond total, returns an empty page rather than an error. Matches with tied relevance can change order between requests, so an ID can occasionally repeat or be skipped at a page boundary.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"q"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}