API Reference (v1)

The Productrise Customer API lets you pull aggregated Google Shopping SERP data into BigQuery, Looker Studio, dbt, Hex, or any reporting stack without scraping the app.

Required plan: Growth or higher.

Quick Start

1. Create an API token from Profile → API Tokens.
2. Call GET /api/v1/properties to list the properties you can access.
3. Pick a property slug and call one of the metrics endpoints.

# 1) List your accessible properties
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties"

# 2) Use one slug from that response
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/top-sellers?start=2026-04-01&end=2026-04-30"

Authentication

Pass your token in the Authorization header:

Authorization: Bearer 42|prsk_AbCdEf1234567890aBcDeF1234567890aBcDeF12abcdefab

Notes:

• The plaintext token is shown once when it is created.
• Maximum 10 active tokens per user.
• Token names are unique per user and max 60 characters.
• All tokens for the same user share one rate-limit budget.

How to find your property slug

You can often see a property slug in Productrise URLs. For example:

https://my.productrise.app/insights/query-groups/v0JEvd-productriseapp

In this case, the slug is v0JEvd-productriseapp.

Best method: use the API directly:

GET /api/v1/properties

This returns all properties your account can query, including each property slug.

Response format

Every successful response uses this envelope:

{
  "data": { ... } or [ ... ],
  "meta": {
    "as_of": "2026-05-06T10:00:00+00:00",
    "...": "endpoint-specific fields"
  }
}

Every non-2xx response uses:

{ "error": { "code": "machine_code", "message": "Human description" } }

Endpoints and parameters

1) GET /api/v1/properties

Purpose: list all accessible properties (owned + shared).

Parameters: none.

curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties"

2) GET /api/v1/properties/{property}

Purpose: fetch one property by slug.

Parameters:

• property (path, required): property slug.

curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme"

3) GET /api/v1/properties/{property}/queries

Purpose: list query IDs for this property (used as query_id filters).

Parameters:

• property (path, required): property slug.

curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/queries"

4) GET /api/v1/properties/{property}/query-groups

Purpose: list query group IDs for this property (used as query_group_id filters).

Parameters:

• property (path, required): property slug.

curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/query-groups"

5) GET /api/v1/properties/{property}/top-sellers

Purpose: top sellers by listing count for a date range.

Parameters:

• property (path, required): property slug.
• start (query, required): YYYY-MM-DD UTC, inclusive.
• end (query, required): YYYY-MM-DD UTC, inclusive, must be >= start and <= today.
• query_id (query, optional): integer query ID for this property. Mutually exclusive with query_group_id.
• query_group_id (query, optional): integer query group ID for this property. Mutually exclusive with query_id.
• top_n (query, optional): integer 1..1000, default 10.
• listing (query, optional): organic or paid. Omit to include both.

Copy-paste examples:

# Required only
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/top-sellers?start=2026-04-01&end=2026-04-30"

# With top_n
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/top-sellers?start=2026-04-01&end=2026-04-30&top_n=25"

# With listing filter
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/top-sellers?start=2026-04-01&end=2026-04-30&listing=organic"

# With query_id filter
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/top-sellers?start=2026-04-01&end=2026-04-30&query_id=123"

# With query_group_id filter
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/top-sellers?start=2026-04-01&end=2026-04-30&query_group_id=45"

6) GET /api/v1/properties/{property}/total-products

Purpose: total product listings observed in the date range.

Parameters:

• property (path, required): property slug.
• start (query, required): YYYY-MM-DD UTC, inclusive.
• end (query, required): YYYY-MM-DD UTC, inclusive, must be >= start and <= today.
• query_id (query, optional): integer query ID for this property. Mutually exclusive with query_group_id.
• query_group_id (query, optional): integer query group ID for this property. Mutually exclusive with query_id.

Copy-paste examples:

# Required only
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/total-products?start=2026-04-01&end=2026-04-30"

# With query_id
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/total-products?start=2026-04-01&end=2026-04-30&query_id=123"

# With query_group_id
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/total-products?start=2026-04-01&end=2026-04-30&query_group_id=45"

7) GET /api/v1/properties/{property}/share-of-voice

Purpose: brand share of total listings using property seller_name.

Parameters:

• property (path, required): property slug.
• start (query, required): YYYY-MM-DD UTC, inclusive.
• end (query, required): YYYY-MM-DD UTC, inclusive, must be >= start and <= today.
• query_id (query, optional): integer query ID for this property. Mutually exclusive with query_group_id.
• query_group_id (query, optional): integer query group ID for this property. Mutually exclusive with query_id.

Copy-paste examples:

# Required only
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/share-of-voice?start=2026-04-01&end=2026-04-30"

# With query_id
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/share-of-voice?start=2026-04-01&end=2026-04-30&query_id=123"

# With query_group_id
curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://my.productrise.app/api/v1/properties/acme/share-of-voice?start=2026-04-01&end=2026-04-30&query_group_id=45"

Important: if seller_name is not set on the property, this endpoint returns 422 seller_name_not_set.

Error codes

• 401: missing, invalid, or revoked token.
• 402 plan_upgrade_required: API access not enabled on your plan.
• 404 property_not_found: property does not exist or you do not have access.
• 422 validation_failed: invalid parameters.
• 422 seller_name_not_set: share-of-voice requested on a property without seller name.
• 429 rate_limited: more than 120 requests per minute.

Technical details and limitations

• Rate limit: 120 requests/minute per authenticated user.
• All tokens for a user share one budget.
• Dates are UTC and inclusive.
• top_n has a max of 1000.
• No pagination in v1 endpoints.
• All success responses include meta.as_of.

Want a new API feature?

We actively shape the API roadmap based on real customer workflows. If you need something that is not in v1 yet, such as per-property token scopes, async exports, webhooks, or OpenAPI/SDK support, please email us at hello@productrise.app.

Include your use case, expected data shape, and how often you need the data. That context helps us prioritize and design features that are useful in production, not just technically possible.