> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pinnacle.sh/v-2/api-reference/tools/get-url/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server.

# Get Shortened URL

GET https://api.pinnacle.sh/tools/url/{linkId}

Retrieve configuration and details for your shortened URL using its unique identifier.

Reference: https://docs.pinnacle.sh/api-reference/tools/get-url

## Authentication

- `PINNACLE-API-KEY` header (required) — API Key authentication via header

## Request

### Path parameters

- `linkId` (string, required) — Unique identifier from your shortened URL. For example, for `https://pncl.to/ePzVxILF`, the `linkId` is `ePzVxILF`.  See the response of [Create Shortened URL](./create-url) for more information.

## Response

### 200

Returns your URL details.

- `clicks` (list of LinkClickEvent, required) — Array of click analytics data for this URL.  Click data will be empty if no one has visited your link yet.
- `config` (PinnacleUrlConfig, required)
- `url` (string, required) — Your custom shortened link following the format `https://pncl.to/{linkId}`, where `{linkId}` is the unique identifier for the URL that can be used with our other endpoint.

## Errors

### 400 Bad Request Error

Validation failed. The payload has missing required fields and/or invalid types.  See [https://zod.dev/error-formatting](https://zod.dev/error-formatting) for more information.

- `description` (string, required) — Human-readable summary of validation failures.
- `errors` (ZodErrorErrors, required) — Structured dictionary of issues containing two main sections: - `errors`: Array of global validation errors not tied to specific fields - `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array

### 401 Unauthorized Error

The request lacks valid authentication credentials or the provided credentials are invalid.  Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.

- `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code.

### 403 Forbidden Error

Your subscription does not include access to this feature.  This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.

- `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code.

### 500 Internal Server Error

An unexpected error occurred on Pinnacle's servers while processing your request.  If this error persists, please contact support with the request details.

- `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code.

## Types

### LinkClickEvent

- `created_at` (string, required) — Timestamp when the click occurred in ISO 8601 format.
- `accept_language` (string, optional, nullable) — Accept-Language header value.
- `accuracy_radius_km` (integer, optional, nullable) — Accuracy radius for geographic coordinates in kilometers.
- `asn` (integer, optional, nullable) — Autonomous System Number.
- `blocked_reason` (string, optional, nullable) — Reason why the request was blocked (if applicable).
- `ch_ua_brand` (string, optional, nullable) — User-Agent Client Hint brand.
- `ch_ua_mobile` (string, optional, nullable) — User-Agent Client Hint mobile indicator.
- `ch_ua_platform` (string, optional, nullable) — User-Agent Client Hint platform.
- `city` (string, optional, nullable) — City name.
- `color_depth` (integer, optional, nullable) — Color depth in bits.
- `connection_type` (string, optional, nullable) — Type of internet connection.
- `country` (string, optional, nullable) — Country code (ISO 3166-1 alpha-2).
- `error_details` (LinkClickEventErrorDetails, optional, nullable) — Error details if the request failed.
- `fbclid` (string, optional, nullable) — Facebook Click Identifier.
- `final_url` (string, optional, nullable) — Final resolved URL after redirects.
- `fingerprint_id` (string, optional, nullable) — Unique fingerprint identifier for the client.
- `gclid` (string, optional, nullable) — Google Click Identifier.
- `ip_address` (string, optional, nullable) — IP address of the visitor (may be anonymized).
- `ip_chain` (list of string, optional, nullable) — Chain of IP addresses for proxied requests.
- `is_bot` (boolean, optional, nullable) — Whether the request was identified as coming from a bot.
- `latency_ms` (integer, optional, nullable) — Request latency in milliseconds.
- `latitude` (double, optional, nullable) — Geographic latitude.
- `longitude` (double, optional, nullable) — Geographic longitude.
- `metadata` (LinkClickEventMetadata, optional, nullable) — Additional metadata as JSON object.
- `method` (string, optional, nullable) — HTTP method used.
- `metro_code` (integer, optional, nullable) — Metro area code.
- `network_downlink` (double, optional, nullable) — Network downlink speed estimate in Mbps.
- `network_rtt` (integer, optional, nullable) — Network round-trip time in milliseconds.
- `performance_ttfb_ms` (integer, optional, nullable) — Time to first byte in milliseconds,.
- `postal_code` (string, optional, nullable) — Postal/ZIP code.
- `redirect_hops` (integer, optional, nullable) — Number of redirect hops to reach final destination.
- `referrer` (string, optional, nullable) — The referring URL.
- `referrer_domain` (string, optional, nullable) — Domain of the referring URL.
- `region` (string, optional, nullable) — Region or state.
- `resolved_at` (string, optional, nullable) — Timestamp when the redirect was resolved in ISO 8601 format.
- `screen_res` (string, optional, nullable) — Screen resolution.
- `status_code` (integer, optional, nullable) — HTTP status code of the response.
- `timezone_offset_min` (integer, optional, nullable) — Timezone offset in minutes from UTC.
- `tor_exit_node` (boolean, optional, nullable) — Whether the request came from a Tor exit node.
- `ua_browser` (string, optional, nullable) — Browser name.
- `ua_device` (string, optional, nullable) — Device type.
- `ua_os` (string, optional, nullable) — Operating system.
- `ua_version` (string, optional, nullable) — Browser version.
- `user_agent` (string, optional, nullable) — User agent string from the browser.
- `utm_campaign` (string, optional, nullable) — UTM campaign parameter.
- `utm_content` (string, optional, nullable) — UTM content parameter.
- `utm_medium` (string, optional, nullable) — UTM medium parameter.
- `utm_source` (string, optional, nullable) — UTM source parameter.
- `utm_term` (string, optional, nullable) — UTM term.

### PinnacleUrlConfig

- `to` (string, required) — Destination URL that your shortened link redirects to.
- `expiresAt` (string, required, nullable) — Expiration date for your shortened link in ISO 8601 format, or null if it's permanent.

### ZodErrorErrors

Structured dictionary of issues containing two main sections: - `errors`: Array of global validation errors not tied to specific fields - `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array

### LinkClickEventErrorDetails

Error details if the request failed.

### LinkClickEventMetadata

Additional metadata as JSON object.

## Examples

**Response**

```json
{
  "clicks": [
    {
      "created_at": "2025-07-09T23:57:28.889+00:00",
      "accept_language": null,
      "accuracy_radius_km": null,
      "asn": null,
      "blocked_reason": null,
      "ch_ua_brand": null,
      "ch_ua_mobile": null,
      "ch_ua_platform": null,
      "city": null,
      "color_depth": null,
      "connection_type": null,
      "country": null,
      "error_details": null,
      "fbclid": null,
      "final_url": null,
      "fingerprint_id": null,
      "gclid": null,
      "ip_address": null,
      "ip_chain": null,
      "is_bot": false,
      "latency_ms": 400,
      "latitude": null,
      "longitude": null,
      "metadata": {},
      "method": "GET",
      "metro_code": null,
      "network_downlink": null,
      "network_rtt": null,
      "performance_ttfb_ms": null,
      "postal_code": null,
      "redirect_hops": 0,
      "referrer": null,
      "referrer_domain": null,
      "region": null,
      "resolved_at": null,
      "screen_res": null,
      "status_code": 302,
      "timezone_offset_min": null,
      "tor_exit_node": null,
      "ua_browser": null,
      "ua_device": null,
      "ua_os": null,
      "ua_version": null,
      "user_agent": "vscode-restclient",
      "utm_campaign": null,
      "utm_content": null,
      "utm_medium": null,
      "utm_source": null,
      "utm_term": null
    }
  ],
  "config": {
    "to": "https://pinnacle.sh",
    "expiresAt": "2023-10-23T16:18:25+00:00"
  },
  "url": "https://pncl.to/ePzVxILF"
}
```

**SDK Code**

```python URL Details
import requests

url = "https://api.pinnacle.sh/tools/url/ePzVxILF"

headers = {"PINNACLE-API-KEY": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript URL Details
const url = 'https://api.pinnacle.sh/tools/url/ePzVxILF';
const options = {method: 'GET', headers: {'PINNACLE-API-KEY': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go URL Details
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pinnacle.sh/tools/url/ePzVxILF"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("PINNACLE-API-KEY", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby URL Details
require 'uri'
require 'net/http'

url = URI("https://api.pinnacle.sh/tools/url/ePzVxILF")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["PINNACLE-API-KEY"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java URL Details
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.pinnacle.sh/tools/url/ePzVxILF")
  .header("PINNACLE-API-KEY", "<apiKey>")
  .asString();
```

```php URL Details
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.pinnacle.sh/tools/url/ePzVxILF', [
  'headers' => [
    'PINNACLE-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp URL Details
using RestSharp;

var client = new RestClient("https://api.pinnacle.sh/tools/url/ePzVxILF");
var request = new RestRequest(Method.GET);
request.AddHeader("PINNACLE-API-KEY", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift URL Details
import Foundation

let headers = ["PINNACLE-API-KEY": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/tools/url/ePzVxILF")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

> One API for RCS, iMessage, MMS, and SMS. Build, test, and scale every channel — send your first message in minutes, not weeks.