xtrakt
Sign inTry for free
Try for free

xtrakt API reference

Get started

Quickstart

From a social media post to JSON in three steps.

  1. Sign in with GitHub.
  2. Create a key under API keys.
  3. Send a post with the request in Extract a post.

Get started

Authentication

Send your key as a Bearer token in the Authorization header of every request.

Authorization: Bearer <API key>

xtrakt is in early access, so API access is turned on by hand. Until your access is on, requests return 403 account_not_enabled.

API reference

Extract a post

Send a link, a prompt and a JSON Schema. xtrakt watches the video, hears the audio and reads the caption, and returns JSON in the shape of your schema.

POST/api/v1/extract

Request
curl https://www.usextrakt.com/api/v1/extract \
  -H "Authorization: Bearer $XTRAKT_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://instagram.com/reel/C8pQ2mLtN4x",
  "prompt": "Extract the recipe.",
  "schema": {
    "type": "object",
    "properties": {
      "dish": { "type": "string" },
      "ingredients": {
        "type": "array",
        "items": { "type": "string" }
      }
    }
  }
}'

Request body

JSON, up to 64 KB. Unknown fields are rejected.

urlString · required

Link to an Instagram post or reel, a YouTube video or Short, a TikTok video, or an X/Twitter post.

  • Instagram posts, reels and tv: /p/, /reel/, /reels/, /tv/
  • YouTube: Shorts, watch?v= and youtu.be links, without extra query parameters
  • TikTok videos: tiktok.com/@user/video/…, vm.tiktok.com/…, vt.tiktok.com/…, tiktok.com/t/… (photo posts are not supported)
  • X/Twitter: x.com/handle/status/id and twitter.com/handle/status/id. Extract one post's text and attached photos, videos and GIFs, including mixed media. Native photo/video permalinks select the whole post.

Links use HTTPS.

promptString · required

What you're looking for, in your own words. 1 to 500 characters.

schemaJSON Schema · required

The shape of the answer. Give each field a description of what it should hold: xtrakt reads it as an instruction. See Writing a schema.

Good to know

  • Public posts and videos work.
  • A request times out after 90 seconds.

API reference

Writing a schema

Describe the answer you want in JSON Schema. The root is {"type": "object"}.

Schema
{
  "type": "object",
  "properties": {
    "dish": {
      "type": "string",
      "description": "Name of the dish"
    },
    "ingredients": {
      "type": "array",
      "description": "Every ingredient, one short name each",
      "items": { "type": "string" }
    },
    "cook_minutes": {
      "type": ["integer", "null"],
      "description": "Total cooking time, or null if not stated"
    }
  },
  "required": ["dish", "ingredients", "cook_minutes"],
  "additionalProperties": false
}

Supported keywords

  • type (string, number, integer, boolean, object, array, null; use ["string", "null"] for optional values)
  • description, title
  • properties, required, additionalProperties (true or false)
  • items, minItems, maxItems
  • enum, minimum, maximum, format (date, date-time, time), anyOf

Other keywords, such as pattern, minLength, const, allOf and $ref, return invalid_schema naming the keyword. A schema can be up to 16 KB, 8 levels deep and 200 nodes.

Tip

Make a field nullable, like ["string", "null"], for details a post may not mention. You get null for those and clean values for the rest.

When a value is not in the video, you get null if your schema allows it. Otherwise the answer may be a best guess.

API reference

Responses

Success (200)

A 200 response holds your JSON under data, in the shape of your schema and ready for your app. The source of the post comes along with it.

A 200 response always matches your schema. As with any extraction, check the values that matter most to you.

source.provider is instagram, tiktok, youtube or x. source.url is the link you sent.

Response · 200
{
  "extraction_id": "ext_0b6f2c1e-8a1d-4f5e…",
  "data": {
    "dish": "Penne all'arrabbiata",
    "ingredients": [
      "penne", "crushed tomatoes", "garlic",
      "red chili", "olive oil", "parsley"
    ]
  },
  "source": {
    "provider": "instagram",
    "url": "https://instagram.com/reel/C8pQ2mLtN4x"
  }
}

Errors

When a request can't complete, the response carries an error with a code and a message instead of data. The codes are listed below.

Response · 400
{
  "extraction_id": "ext_0b6f2c1e-8a1d-4f5e…",
  "error": {
    "code": "invalid_schema",
    "message": "schema.properties.a: unsupported keyword \"pattern\""
  }
}

API reference

Error codes

CodeHTTPMeaning
unauthorized401Missing, wrong or revoked API key.
account_not_enabled403Valid key, but the account has no API access yet.
invalid_request400Bad JSON, unknown field, or bad prompt. Includes a message.
invalid_schema400Schema uses something not supported. Includes a message.
payload_too_large413Request body over 64 KB.
unsupported_url422Not a supported Instagram, TikTok, YouTube or X URL.
url_source_inaccessible422Private, removed or blocked post, or it timed out.
url_source_over_limit422Post too big, or the server is busy. Retry later.
url_video_too_large422A video is over 50 MB.
url_video_too_long422Video too long: YouTube over 30 minutes, Instagram/TikTok over 5 minutes, X over 6 minutes in total.
invalid_extraction502The result could not be made to match your schema.
extraction_failed502Extraction failed or timed out. Retry.
server_misconfigured500Server problem. Report it with the extraction_id.

API reference

Tracing

Every response has an extraction_id, also in the x-extraction-id header. Include it when reporting a problem.