Skip to main content

​
Overview

The URLStats model represents the internal statistics and metadata for a short URL. This model is returned by endpoints that provide detailed information about a URL’s performance and status.

​
When to Use

This model is returned by:
  • GET /details - Retrieve detailed statistics for a short URL
This is a response-only model. You don’t send this data to the API; the API returns it to you.

​
Schema Definition

​
url_code
string
The short code identifier for the URL.This is the unique identifier used in the shortened URL path.
​
url_hits
integer
The total number of times this short URL has been accessed.Tracking:
  • Increments each time someone visits the short URL
  • Can be reset using the /reset_hits endpoint
  • Useful for measuring link popularity and reach
Monitor this metric to understand how often your links are being used
​
url_created_at
datetime
The timestamp when the short URL was created.Format: ISO 8601 datetime stringExample: "2024-03-15T14:30:00.000Z"
Timestamps are typically in UTC timezone
​
url_state
boolean
The current active state of the short URL.Values:
  • true - URL is active and accessible
  • false - URL is paused and will not redirect
State Management:
  • Use /pause endpoint to set to false
  • Use /resume endpoint to set to true
  • Paused URLs return an error or info page instead of redirecting
Paused URLs do not redirect visitors to the destination

​
Example JSON Response

{
  "url_code": "my-link",
  "url_hits": 1247,
  "url_created_at": "2024-01-15T10:30:00.000Z",
  "url_state": true
}

​
Understanding URL States

When url_state is true:
  • The short URL redirects to the destination URL
  • Hit counter increments on each visit
  • URL is fully functional and accessible
  • This is the default state for newly created URLs
When url_state is false:
  • The short URL does not redirect
  • Visitors see an error or informational message
  • Hit counter may or may not increment (depends on implementation)
  • Useful for temporarily disabling a link without deleting it

​
Use Cases

Common Scenarios for Checking URL Stats:
  1. Campaign Tracking - Monitor hits for marketing campaigns
  2. Performance Analysis - Analyze which links get the most traffic
  3. Link Management - Check if a URL is active or paused
  4. Audit Trail - Verify when a URL was created
  5. Capacity Planning - Understand link usage patterns

​
Metrics and Analytics

The url_hits counter provides basic usage metrics:Insights You Can Gain:
  • Total reach of your short link
  • Popularity comparison between different links
  • Traffic trends when combined with creation date
Limitations:
  • Does not track unique visitors (counts all visits)
  • No geographic or demographic information
  • No referrer or device information
Reset hits using /reset_hits to start fresh tracking for a new campaign
Control your URL’s active state:
  • Pause - Set url_state to false (temporary deactivation)
  • Resume - Set url_state to true (reactivation)
  • Check - View current state via /details endpoint
Pausing is useful when:
  • A campaign has ended
  • You need to update the destination URL
  • You want to prevent access without deleting the link

​
Response Headers

When retrieving URL stats, the response typically includes standard HTTP headers with content-type application/json.

​
Date and Time Handling

The url_created_at field uses Python’s datetime type, which is serialized to ISO 8601 format in JSON responses. Parse this format in your application to display human-readable dates.
Example Parsing (JavaScript): 
const createdDate = new Date(stats.url_created_at);
console.log(createdDate.toLocaleDateString()); // "3/15/2024"
Example Parsing (Python): 
from datetime import datetime
created = datetime.fromisoformat(stats['url_created_at'])
print(created.strftime('%Y-%m-%d'))  # "2024-03-15"

Build docs developers (and LLMs) love

Get started for freeTalk to us