Search

Overview

POST /v1/search runs one natural-language search over the current Instagram corpus. It interprets topic, time range, language, region, format, and exclusions and returns the complete ranked result set selected by the search engine.

Search is synchronous and commonly takes 30–60 seconds. Thin-result diagnosis can add more time, so use a client timeout of at least 270 seconds.

Request

POST https://search-backend-s4c56s44ia-uk.a.run.app/v1/search

Headers

• Authorization: required. Bearer sak_live_<KEY_PREFIX>.<SECRET>.
• Content-Type: required. application/json.
• Idempotency-Key: optional but strongly recommended. Use a unique value for each intended search and reuse it with the identical body when retrying. Values must contain 1–255 printable ASCII characters.

For keys with a fixed total search allocation, one unit is consumed only when a new logical search is accepted. Replays and timeout recoveries using the same Idempotency-Key do not consume another unit. See Errors & Rate Limits for the response headers and exhaustion behavior.

Body

{
  "query": "funny love island reactions from the last 90 days"
}

query must contain 2–500 characters when provided. A request must include a query, a reference video, or both. The body is strict: unknown fields, including limit, return 422. Malformed JSON returns 400.

Search using an uploaded MP4

Create a short-lived upload target before searching with a local video file:

POST https://search-backend-s4c56s44ia-uk.a.run.app/v1/reference-uploads

{
  "fileName": "reference.mp4",
  "contentType": "video/mp4",
  "sizeBytes": 12345678
}

The endpoint accepts MP4 files up to 100 MiB and returns 201:

{
  "uploadId": "ref_0123456789abcdef0123456789abcdef",
  "upload": {
    "method": "PUT",
    "url": "https://storage.googleapis.com/...signed parameters...",
    "headers": {
      "content-type": "video/mp4",
      "x-goog-content-length-range": "0,12345678",
      "x-goog-meta-expected-size": "12345678",
      "x-goog-meta-upload-created-at": "2026-08-06T15:00:00.000Z"
    },
    "expiresAt": "2026-08-06T15:15:00.000Z"
  },
  "reference": {
    "uploadId": "ref_0123456789abcdef0123456789abcdef"
  }
}

Upload the raw file bytes to upload.url using the returned method and every returned header. The signed target expires after 15 minutes; this storage request does not use the Search API authorization header.

curl -X PUT "$SIGNED_UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  -H "x-goog-content-length-range: 0,$FILE_SIZE_BYTES" \
  -H "x-goog-meta-expected-size: $FILE_SIZE_BYTES" \
  -H "x-goog-meta-upload-created-at: $UPLOAD_CREATED_AT" \
  --upload-file ./reference.mp4

After the upload succeeds, use the opaque ID in a normal search request:

{
  "query": "find videos similar to this",
  "reference": {
    "uploadId": "ref_0123456789abcdef0123456789abcdef"
  }
}

The upload is scoped to the API key that created it and is accepted for 24 hours. The uploaded byte count must exactly match sizeBytes, the object must retain the returned video/mp4 content type and metadata headers, and its bytes must have an MP4 file signature. Invalid or expired objects are deleted. An ID created by another API key—or an ID whose file was never uploaded—returns 422 with reference_upload_not_found.

The existing reference forms remain available for internal GCS media and Instagram posts:

{ "query": "find similar videos", "reference": { "mediaUrl": "https://storage.googleapis.com/discovery-post-media-bucket/video.mp4" } }

{ "query": "find similar videos", "reference": { "permalink": "https://www.instagram.com/reel/SHORTCODE/" } }

Provide exactly one of uploadId, mediaUrl, or permalink inside reference. When query is omitted, the API uses “Find content similar to the reference video.” Public Instagram posts that are not already in the search corpus are retrieved through the media scraper, archived only for transient analysis, and then removed.

Search behavior

Relevance searches

A query with a topic, product, audience, format, scene, or exclusion runs a relevance search. The API searches analyzed post content, removes posts that do not satisfy the request, and orders the accepted matches by captured likes.

Top-content searches

A leaderboard-style request without a meaningful topic uses the filtered top-content feed:

top content from USA in the last week

This path applies the requested time, language, and region filters directly and orders matching posts by captured likes, highest first. It does not perform topic relevance matching because the request does not contain a topic.

Top and highest-liked refer to engagement captured in the indexed corpus. Terms such as viral, popular, and trending can express ranking intent, but the API does not verify platform-native trend status. It also cannot directly identify trending sounds or audio; when possible, message explains the post-search fallback that was used.

Time, language, and location

Filters are written inside the query:

• Time: last 7 days, past 3 weeks, previous month, last year, and all time are supported. If omitted, the API normally searches the last 30 days. All time means all matching content currently available in the indexed corpus.
• Language: English, Spanish, Russian, Japanese, Chinese/Mandarin, and Korean are recognized. Use wording such as in Spanish. Otherwise, a relevance search uses the query’s language; a subjectless top-content search defaults to English.
• Location: use country or region wording such as from USA, in the UK, from Western Europe, or in Japan. Location matching uses broad indexed region labels rather than exact country geofencing. For example, USA and Canada currently map to the North America region.

Explicit-content posts are excluded. Start broad and add constraints only when they matter; combining a niche topic with a short time range, specific format, audience, language, and location can leave very few matches.

Response

This example is abbreviated to one result. The actual response contains all 50 matches indicated by totalCount.

{
  "requestId": "027f2ee4-121c-4778-bf70-bcb020c3232f",
  "query": "videos of a cat walking around from the last two weeks",
  "message": "I have gathered English-language videos of cats walking or exploring from the last 30 days. This search focused on identifying recent footage where a cat is actively in motion, such as pacing or moving through various indoor and outdoor environments, rather than stationary or sleeping.",
  "suggestions": [],
  "totalCount": 50,
  "results": [
    {
      "id": "1f16e876-64fe-6baf-8b1c-41499ef43eb7",
      "platform": "Instagram",
      "url": "https://www.instagram.com/reel/DZ2sciLttW0/",
      "caption": "As the youngest orange tabby in the house, Maxwell took special care of Sue. #cats",
      "mediaUrl": "https://storage.googleapis.com/discovery-post-media-bucket/video-1f16e876-64fe-6baf-8b1c-41499ef43eb7.mp4",
      "creatorHandle": "@doushabao2cat",
      "postedAt": "2026-06-21T16:28:50.000Z",
      "metrics": {
        "likes": 1000000,
        "comments": 7731
      },
      "subject": "First-person perspective of cat walking and chasing"
    }
  ]
}

Top-level fields

• requestId: identifier for this logical search. The same value is also returned in X-Request-Id and is preserved by idempotent replays.
• query: the query you sent.
• message: the search summary. For thin searches, the completed diagnosis is appended before the response is returned.
• suggestions: up to three standalone alternative queries for a thin search; otherwise an empty array.
• totalCount: the number of items in results.
• results: all ranked matches selected by the search engine, best first.

Result fields

• id: post identifier for GET /v1/posts/:id.
• platform: source platform, currently Instagram for search results.
• url: public Instagram post URL.
• caption: original caption.
• mediaUrl: GCS-hosted video URL. Clients can display the video’s first frame or generate their own poster image.
• creatorHandle: creator handle.
• postedAt: ISO 8601 publication timestamp.
• metrics: captured likes and comments counts.
• subject: concise description of what the post is about, or null.

The v1 response intentionally does not include thumbnails or match highlights.

Thin and zero-result searches

When a search returns few or no matches, the API diagnoses the result before responding. A zero-result search is still a successful 200 response:

• totalCount is 0 and results is an empty array.
• A short diagnosis is appended to message.
• suggestions contains up to three complete alternative queries that preserve the broad intent while relaxing a likely blocking constraint.
• The diagnosis can consider language, format, audience, exclusions, explicit content filtering, location, and time range. A wider time range is suggested only when a probe indicates that it is likely to help.

The API does not automatically run the suggested queries. To try one, send it as the query in a new POST /v1/search with a new Idempotency-Key.

{
  "requestId": "24f35dbc-5115-4374-a943-deef53d90ed3",
  "query": "concert vlog from a house show",
  "message": "I'm returning posts for \"concert vlog from a house show\" across English posts, the last 30 days, and format narrative and vlog. I found adjacent posts, but most were missing one of the required details in the full request. Try removing one constraint, like the format or audience qualifier, then refine from there.\n\nYour search may be too narrow. Try these broader terms or a wider date range to find more house show vlogs.",
  "suggestions": [
    "concert vlog from a house show from last 90 days",
    "house show concert experience",
    "live music house show vlog"
  ],
  "totalCount": 0,
  "results": []
}

Example request

curl -sS -X POST "https://search-backend-s4c56s44ia-uk.a.run.app/v1/search" \
  -H "Authorization: Bearer sak_live_YOUR_KEY_PREFIX.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-$(uuidgen)" \
  --max-time 270 \
  -d '{
    "query": "funny love island reactions from the last 90 days"
  }'