# itemIdsByUrl

Query

Look up item IDs by social media URLs within the current workspace. Accepts any public HTTP(S) URL. INVALID_URL is returned only for malformed / non-HTTP URLs or private/reserved hosts; a valid public URL we cannot resolve (unrecognized shape, short link, or no matching item) returns NOT_FOUND. Recognized shapes (non-exhaustive hint): Instagram (/p/, /reel/, /reels/), TikTok (@user/video/{id}, @user/photo/{id}), and YouTube (/shorts/, /watch?v=, youtu.be/).

Available to agents as MCP tool `getItemIdsByUrl` — see [Read tools](/api/v2/docs/mcp/read-tools#get-item-ids-by-url).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `urls` | `[String!]!` | Yes | — | Public HTTP(S) URLs to look up (1-100). Any public URL is accepted; INVALID_URL only for malformed / non-HTTP URLs or private/reserved hosts, otherwise FOUND or NOT_FOUND. |

## Returns

Returns [`[UrlLookupResult!]!`](/api/v2/docs/types/url-lookup-result).

## Examples

### Look up item IDs by URL

Resolve social media URLs to workspace item IDs.

```graphql
query ItemIdsByUrlDefault($urls: [String!]!) {
  itemIdsByUrl(urls: $urls) {
    url
    itemId
    status
  }
}
```

Variables:

```json
{
  "urls": [
    "https://www.instagram.com/p/docs-item-0/"
  ]
}
```

Response — HTTP 200:

```json
{
  "data": {
    "itemIdsByUrl": [
      {
        "url": "https://www.instagram.com/p/docs-item-0/",
        "itemId": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
        "status": "FOUND"
      }
    ]
  }
}
```