REST API · VERSION 1 · JSON

From public URL
to usable media.

Resolve supported Instagram, TikTok, X/Twitter, Pinterest and Telegram public URLs through one authenticated endpoint and one normalized response format.

BASE URLhttps://developers.getinsaver.com/v1HTTPS only · UTF-8 JSON

Public content only. The API does not bypass privacy controls, authentication, deleted content, geographic restrictions, or platform rights controls. Failed lookups consume zero credits.

Authentication

Every production request uses a server-side Bearer API key.

Create a key under Dashboard → API keys. The complete key is shown once and only a one-way hash is stored. Send it in the Authorization header:

Authorization: Bearer gis_live_YOUR_API_KEY

Store keys in a secret manager or server environment variable.
Use separate keys for production, staging, and individual products.
Revoke a key immediately if it may have leaked.

Do not

Embed keys in browser JavaScript or mobile application binaries.
Commit keys to Git or paste them into screenshots and tickets.
Proxy arbitrary end-user URLs without validation or abuse controls.

Quickstart

Send one public URL and receive normalized media items.

curl https://developers.getinsaver.com/v1/resolve \
  --request POST \
  --header "Authorization: Bearer $GETINSAVER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "service": "instagram",
    "url": "https://www.instagram.com/reel/SHORTCODE/",
    "max_results": 10
  }'

const response = await fetch("https://developers.getinsaver.com/v1/resolve", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GETINSAVER_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    service: "instagram",
    url: "https://www.instagram.com/reel/SHORTCODE/",
    max_results: 10
  })
});

const result = await response.json();
if (!response.ok) throw new Error(`${result.code}: ${result.message}`);
console.log(result.items);

import os
import requests

response = requests.post(
    "https://developers.getinsaver.com/v1/resolve",
    headers={"Authorization": f"Bearer {os.environ['GETINSAVER_API_KEY']}"},
    json={
        "service": "instagram",
        "url": "https://www.instagram.com/reel/SHORTCODE/",
        "max_results": 10,
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["items"])

Resolve media

The single production endpoint for every supported service.

POST/v1/resolveBearer authapplication/json

Request body

Field	Type	Required	Rules	Description
`service`	string	required	Supported ID	Determines URL validation, upstream workflow, and item multiplier.
`url`	string	required	HTTP(S), ≤ 2048 chars	A publicly accessible URL whose hostname and path match the selected service.
`max_results`	integer	optional	1–20; default 10	Maximum items returned and the basis of the temporary credit reservation.

Successful response

{
  "ok": true,
  "request_id": "39a3bff5-…",
  "service": "instagram",
  "source_url": "https://www.instagram.com/reel/SHORTCODE/",
  "item_count": 1,
  "credits_used": 1,
  "items": [
    { "type": "video", "url": "https://cdn.example/media.mp4" }
  ],
  "metadata": {
    "title": null,
    "author": "creator",
    "caption": null
  }
}

Field	Type	Description
`request_id`	UUID	Unique usage-ledger identifier for support and reconciliation.
`service`	string	The service ID used for the request.
`source_url`	string	Normalized source URL, with the fragment removed.
`item_count`	integer	Number of media items returned.
`credits_used`	integer	Final charge after unused reserved credits are returned.
`items[].type`	enum	`video`, `image`, or `audio`.
`items[].url`	URL	Resolved media URL. Treat it as temporary and consume it promptly.
`metadata`	object	Best-effort title, author, and caption. Individual fields may be `null`.

Service IDs and item cost

The live catalog is the source of truth for identifiers and multipliers.

Loading live service catalog…

Instagram Posts/Reels, Stories, and Highlights are separate service IDs because their URL rules and credit multipliers differ. Selecting the wrong ID returns URL_INVALID and consumes zero credits.

Errors

Use the HTTP status for control flow and the stable code for diagnostics.

{
  "error": true,
  "code": "UPSTREAM_REJECTED",
  "message": "Media could not be resolved."
}

Status	Common codes	Action
400	`SERVICE_UNSUPPORTED` `URL_INVALID`	Correct the selected service, hostname, path, or body.
401	`API_KEY_INVALID`	Send a valid, non-revoked key from a verified active account.
402	`INSUFFICIENT_CREDITS`	Add credits or lower `max_results` before retrying.
422	`MEDIA_NOT_FOUND` `UPSTREAM_REJECTED`	Confirm the URL is public, supported, active, and available.
429	`RATE_LIMITED`	Read the `RateLimit` header and retry after the window resets.
502	`UPSTREAM_INVALID_RESPONSE` `UPSTREAM_ERROR`	Retry with bounded exponential backoff.
504	`UPSTREAM_TIMEOUT`	Retry later; do not immediately fan out duplicate requests.

Failures are not charged. If resolution fails after a reservation, the full reservation is returned and the usage ledger records zero credits used.

Credits and metering

Concurrency-safe reservation with exact item-level settlement.

1Reserve

max_results × multiplier

→

2Resolve

Process the public URL

→

3Settle

Charge returned items only

A five-item Instagram carousel on the 1× service costs 5 credits.
Three active Story items on the 2× service cost 6 credits.
A private, deleted, expired, invalid, or failed lookup costs 0 credits.
Credits are prepaid, do not expire, and the dashboard exposes both usage and credit ledgers.

Rate limits and retries

Predictable defaults for self-service production workloads.

120gateway requests / minute / API key

20maximum returned items / request

120smaximum upstream processing window

Rate-limit responses include a standard RateLimit header. Retry 429, 502, and 504 with capped exponential backoff and jitter. Do not retry validation errors. For higher concurrency, isolated capacity, or a private deployment, request a commercial proposal.

Security and acceptable use

Build a server-side integration with clear rights and abuse boundaries.

Submit only URLs you are legally permitted to process. Do not use the API to infringe copyright, evade access controls, facilitate harassment, or create unlawful surveillance. Public availability does not itself grant redistribution rights. Media URLs can expire; download or transform them only when your rights and the originating platform rules allow it.

Production launch checklist

The essentials before exposing your integration to real users.

Keep the API key exclusively on your server. Validate the platform and URL before calling the API. Set an intentional max_results for predictable reservations. Handle every documented HTTP status and preserve request_id in logs. Add bounded retries for 429, 502, and 504. Consume temporary media URLs promptly and enforce your rights policy.

NEED A SECOND SET OF EYES?

Ship your integration with confidence.

Use the 20 free results for an end-to-end test, or ask us about volume planning, private Docker, and source-available OEM terms.

Create free account →Contact commercial team

From public URLto usable media.