---
title: "Identify an X URL"
method: GET
path: "/v1/x/resolve-url"
---

# Identify an X URL

`GET /v1/x/resolve-url`

## Request

- Base URL: `https://api.veezee.io`
- URL: `https://api.veezee.io/v1/x/resolve-url`
- Auth: HTTP bearer

Identify what an X (formerly Twitter) URL points at before fetching it. Give any x.com or twitter.com URL (mobile links, query params, /i/web/status forms are fine); get back {type: profile|tweet, id, handle, canonical_url}. Tweet URLs yield the numeric id for x_get_tweet; profile URLs yield the handle for x_get_profile or x_get_tweets. Costs 2 credits and parses offline without fetching the page. t.co short links cannot be expanded offline and return INVALID_INPUT telling you so; expand them in your own browser step first. Skip this tool when you already have a handle or tweet id: the other X tools accept those directly.

## Query parameters

- `url` string, required: An X URL, e.g. https://x.com/nasa/status/2054497961162478079 or https://twitter.com/nasa.

## Headers

- `Idempotency-Key` string

## Response `200`

url_resolution envelope (schema_version 2)

- UrlResolutionEnvelope
  - `entity` 'url_resolution', required
  - `platform` 'linkedin' | 'reddit' | 'x', nullable, required
  - `canonical_url` string, nullable, required
  - `data_as_of` string, nullable, required
  - `schema_version` '2', required
  - `common` object, required
    - `input_url` string, required
    - `type` 'person' | 'company' | 'post' | 'subreddit' | 'user' | 'comment' | 'profile' | 'tweet', required: What the URL points at, in the platform's own vocabulary.
    - `id` string, nullable, required: Stable platform id (URN, t3_/t1_ id, or numeric id) when resolvable.
    - `handle` string, nullable, required: Human-readable slug or handle when present in the URL.
    - `canonical_url` string, nullable, required
  - `platform_fields` object, required
  - `freshness` object, nullable, required
    - `source_retrieved_at` string, nullable, required: When the data was fetched from the source. ISO 8601.
    - `served_at` string, required
    - `cache_age_seconds` integer, nullable, required
    - `served_from_cache` boolean, required: True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are.
    - `freshness_requested` 'recent' | 'realtime', required
    - `freshness_served` 'recent' | 'realtime' | 'stale', required
  - `usage` object, required
    - `receipt_id` string, nullable, required
    - `credits_quoted` integer, required
    - `credits_charged` integer, required
    - `balance_remaining` integer, nullable, required
    - `free_tier_hint` string: Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key. Near the daily cap on unclaimed keys it also carries a claim link to relay to your human (claiming adds one-time credits).

## Other responses

- `400`: INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED
- `401`: UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED
- `402`: INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS
- `403`: NOT_ENTITLED | TRIAL_CAP_EXCEEDED
- `404`: NOT_FOUND
- `409`: IDEMPOTENCY_KEY_REUSED
- `413`: PAYLOAD_TOO_LARGE
- `429`: CONCURRENCY_LIMIT | RATE_LIMITED
- `500`: INTERNAL
- `502`: UPSTREAM_UNAVAILABLE
- `503`: BUDGET_EXHAUSTED

---

[API](https://skmtc.dev/veezee/apis/veezee-api.md) · [All operations](https://skmtc.dev/veezee/apis/veezee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/veezee/apis/veezee-api/revisions/6f1831474e70?raw)