Making Requests

Learn how to structure API requests to Ghost Metrics.

Request Structure

Every API request follows this basic structure:


https://[your-subdomain].ghostmetrics.cloud/?module=API&method=[Module].[Method]&[parameters]

Required Components

Component	Description	Example
Base URL	Your Ghost Metrics instance	`https://example.ghostmetrics.cloud/`
`module=API`	Always required	`module=API`
`method`	The API method to call	`method=VisitsSummary.get`

Common Parameters

Most reporting methods also require:

Parameter	Description	Example
`idSite`	Website ID	`idSite=1`
`period`	Time period	`period=day`
`date`	Date or date range	`date=yesterday`
`format`	Response format	`format=JSON`
`token_auth`	Authentication token	`token_auth=abc123`
`segment`	Optional visitor filter — see Segmentation	`segment=deviceType==smartphone`

HTTP Methods

GET Requests

Simple to use, good for testing:


curl "https://example.ghostmetrics.cloud/?module=API&method=VisitsSummary.get&idSite=1&period=day&date=yesterday&format=JSON&token_auth=YOUR_TOKEN"

POST Requests (Recommended)

More secure — token doesn’t appear in URL:


curl -X POST "https://example.ghostmetrics.cloud/" \
  -d "module=API" \
  -d "method=VisitsSummary.get" \
  -d "idSite=1" \
  -d "period=day" \
  -d "date=yesterday" \
  -d "format=JSON" \
  -d "token_auth=YOUR_TOKEN"

Date Parameters

Single Dates

Value	Description
`today`	Current day (based on website timezone)
`yesterday`	Previous day
`2024-01-15`	Specific date (YYYY-MM-DD)

Multi-Period Ranges

These return one row of data per period (e.g., one per day with period=day):

Value	Description
`last7`	Last 7 periods including today
`last30`	Last 30 periods including today
`previous7`	7 periods before today (not including today)
`previous30`	30 periods before today

Custom Date Ranges

For period=range, specify start and end dates — magic keywords work as endpoints too:


&period=range&date=2024-01-01,2024-01-31
&period=range&date=2024-01-01,today

Period Parameters

Value	Description
`day`	Daily data
`week`	Weekly data (weeks containing the date)
`month`	Monthly data
`year`	Yearly data
`range`	Custom date range (aggregated)

Period + Date Examples


# Yesterday's data
&period=day&date=yesterday

# This week's data
&period=week&date=today

# Last month's data
&period=month&date=lastMonth

# Last 7 days (one row per day)
&period=day&date=last7

# Last 7 days (aggregated into one result)
&period=range&date=last7

# Custom range
&period=range&date=2024-01-01,2024-01-31

Response Formats

JSON (Recommended)


&format=JSON


[
  {
    "label": "United States",
    "nb_visits": 1250,
    "nb_actions": 3420
  },
  {
    "label": "Canada",
    "nb_visits": 543,
    "nb_actions": 1205
  }
]

XML


&format=xml


<?xml version="1.0" encoding="utf-8" ?>
<result>
  <row>
    <label>United States</label>
    <nb_visits>1250</nb_visits>
    <nb_actions>3420</nb_actions>
  </row>
</result>

CSV


&format=csv


label,nb_visits,nb_actions
United States,1250,3420
Canada,543,1205

TSV (Excel-friendly)


&format=tsv

Tab-separated values that open correctly in Excel.

Limiting Results

Row Limits


# Return only top 10 results
&filter_limit=10

# Return all results (no limit)
&filter_limit=-1

By default, the API returns the top 100 rows.

Pagination


# Skip first 10, return next 10
&filter_offset=10&filter_limit=10

Sorting Results


# Sort by visits descending
&filter_sort_column=nb_visits&filter_sort_order=desc

# Sort by label alphabetically
&filter_sort_column=label&filter_sort_order=asc

Filtering Results

Show Specific Columns


# Only return visits and actions
&showColumns=nb_visits,nb_actions

Hide Columns


# Hide the logo column
&hideColumns=logo

Filter by Label


# Only rows containing "google"
&filter_pattern=google&filter_column=label

Bulk Requests

Request multiple API methods in a single HTTP call:


https://example.ghostmetrics.cloud/?module=API
  &method=API.getBulkRequest
  &format=JSON
  &urls[0]=method%3DVisitsSummary.get%26idSite%3D1%26period%3Dday%26date%3Dyesterday
  &urls[1]=method%3DUserCountry.getCountry%26idSite%3D1%26period%3Dday%26date%3Dyesterday
  &token_auth=YOUR_TOKEN

Each URL in the urls[] array must be URL-encoded. For more than a handful of requests, send the bulk call as a POST (with the urls[] values in the body) to avoid URL length limits.

The response contains an array with results for each request:


[
  { "nb_visits": 1543, "nb_actions": 4521 },
  [
    { "label": "United States", "nb_visits": 500 },
    { "label": "Canada", "nb_visits": 200 }
  ]
]

Error Handling

Successful Response

Returns the requested data in your chosen format.

Error Response


{
  "result": "error",
  "message": "You are not authorized to access this resource."
}

Common Errors

Error	Cause	Solution
”Not authorized”	Invalid or missing token	Check token_auth parameter
”Invalid site”	Wrong idSite	Verify website ID
”Invalid date”	Malformed date	Use YYYY-MM-DD format
”Invalid period”	Unknown period value	Use day, week, month, year, or range

Request Examples

Get Visit Summary


?module=API
&method=VisitsSummary.get
&idSite=1
&period=day
&date=yesterday
&format=JSON
&token_auth=YOUR_TOKEN

Get Top Pages


?module=API
&method=Actions.getPageUrls
&idSite=1
&period=month
&date=today
&format=JSON
&filter_limit=10
&token_auth=YOUR_TOKEN

Get Traffic Sources


?module=API
&method=Referrers.getAll
&idSite=1
&period=week
&date=today
&format=JSON
&token_auth=YOUR_TOKEN

Get Goal Conversions


?module=API
&method=Goals.get
&idSite=1
&period=month
&date=today
&idGoal=1
&format=JSON
&token_auth=YOUR_TOKEN

Multiple Sites

Query multiple websites at once:


&idSite=1,2,3

Or all sites:


&idSite=all

Note: Not all methods support multiple sites.

Next Steps

Parameters Reference — Complete parameter documentation
Segmentation — Filter data with segments
Common Methods — Most-used API methods
Code Examples — Working code samples