List all installs

GET 
https://api.freemius.com/v1/products/{product_id}/installs.json

Auth:Bearer TokenSCOPE: PRODUCT

Product-scoped API tokens allow you to operate on the product itself. This token usually allows read-only access to the product configuration and write access to several operations on subscriptions, customers, payments, and more. For most SaaS or app integrations, this is the token you will need.

1. Go to the Freemius Developer Dashboard.
2. Open the Settings page of the relevant product.
3. Click the API & Keys tab.
4. Copy the API Bearer Authorization Token from the UI.

---

Retrieve the install collection associated with the product.

Various filtering and search parameters are available to narrow down the results.

Request

Path Parameters

product_id integer<int64>required
The ID of the product.
Possible values: >= 1
Example: 1234

Query Parameters

ids string<comma-separated>
Install IDs collection to filter.
Example: 1234,2478,2345
filter string

Install status to filter the installs by.

Possible values: [all, active, inactive, trial, paying, uninstalled, active_premium, active_free]

version string

Plugin version to filter the installs by.

license_id integer

License ID to filter the installs by.

plan_id integer

Plan ID to filter the installs by.

title string

Install title to filter the installs by.

url string

Install URL to filter the installs by.

search string

Search item to filter the installs by e.g. domain, site_id, or reason info.

all boolean

Default value: false

If true, loads all installs, including the uninstalled ones.

reason_id string

Reason ID (either string or numeric) to filter the installs by.

count integer
Default value: 25
The number of records to return.
Possible values: >= 1 and <= 50
Example: 10
offset integer
Default value: 0
The number of records to skip before starting to return records. Default is 0.
Possible values: >= 0
Example: 10
fields string
Comma separated list of fields to return in the response. If not specified, all fields are returned.
Example: id,name,slug

Responses

200

Installs collection

application/json

Schema

installs object[]

Array [

secret_keystring

The secret key associated with the entity for authorization.

Example: sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

public_keystring

The public key associated with the entity for authorization.

Example: pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456

createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00

updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00

site_idstring<int64>

The ID of the site.

Example: 1234

plugin_idstring<int64>

The ID of the product the entity belongs to.

Possible values: >= 1

Example: 123456

user_idstring<int64>

The ID of the user the entity belongs to.

Possible values: >= 1

Example: 123456

urlstringnullable

The site URL.

Example: https://example.com

titlestringnullable

The site title.

Example: Catwalk Designs

versionstring

The Product version.

Example: 1.0.0

plan_idstring<int64>

The ID of the plan associated with the product that the install has a license activation. If null it means the install is using the free plan.

Possible values: >= 1

Example: 1234

license_idstring<int64>nullable

The ID of the license associated with the entity.

Possible values: >= 1

Example: 123456

trial_plan_idstring<int64>

The ID of the trial license associated to the product. If this is not a trial, this will be null.

Possible values: >= 1

Example: 1234

trial_endsstring<date-time>nullable

The product trial license expiry date. If this is not a trial, this will be null.

Example: 2025-01-01 00:00:00

subscription_idstring<int64>nullable

The ID of the subscription associated with the entity.

Possible values: >= 1

Example: 123456

grossnumber<float>

The gross amount the install has spent on the product. This includes one time purchase, or subscriptions and renewals.

Example: 100

country_codestringnullable

The ISO 3166-1 alpha 2 two-letter country code associated with the entity.

Example: us

languagestringnullable

The language specified for the product install.

Example: en-GB

platform_versionstringnullable

The platform version (e.g WordPress version).

Example: 1.0.0

sdk_versionstringnullable

The Freemius SDK version. Only relevant for WordPress products using the Freemius WP SDK.

Example: 1.2.2

programming_language_versionstringnullable

The programming language version (e.g PHP version).

Example: 5.6

is_activeboolean

If the product is actively installed on the site.

is_disconnectedboolean

If the product is disconnected on the site.

is_premiumboolean

If the install using the premium code. Relevant only for WP Products.

is_uninstalledboolean

If the product is uninstalled on the site.

is_lockedboolean

If the product is locked on the site.

sourcenumber

The source of the migration data. To get support migrating from other platform please see our documentation.

• 0 - Freemius
• 1 - Other
• 2 - Easy Digital Downloads (EDD)
• 3 - WooCommerce (WC)
• 4 - Rating Widget
• 5 - Gumroad
• 6 - CodeCanyon
• 7 - ThemeForest
• 8 - AppSumo
• 9 - SendOwl
• 10 - WHMCS
• 11 - Lemon Squeezy

Possible values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

upgradedstring<date-time>nullable

Time when the product was upgraded to the current version. If never upgraded since the initial installation, this will be null.

Example: 2025-01-01 00:00:00

last_seen_atstring<date-time>nullable

The last time the product was used on the site.

Example: 2025-01-01 00:00:00

last_served_update_versionstringnullable

The last product version update used on the site. If not updated, this will be null.

Example: 1.2.2

]

400

Bad request. The request could not be understood by the server due to malformed syntax or arguments.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

401

Unauthorized access error. The request requires authentication but was not provided or the provided authentication does not satisfy the required permissions.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

402

The request is missing the specified argument.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

404

The requested resource was not found.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}