Store, reviews & issues

Browse public Actors in the Scrape.ly Store, read and submit reviews, and manage issue reports on public Actors. Paths are relative to https://api.scrape.ly. See API Reference for authentication and response conventions, and Find Actors in the Store for the dashboard view.

On endpoints marked "authentication optional", omit the Authorization header to call them anonymously. An invalid token still returns 401.

List Store Actors

Lists published, non-deprecated Actors. /v2/store is the same endpoint under the path existing Store API clients use. Authentication optional. Existing Store API clients can send the same parameters.

curl "https://api.scrape.ly/v2/store/actors?search=scraper&category=ECOMMERCE&sortBy=popularity&limit=20"

{
  "data": {
    "total": 128,
    "offset": 0,
    "limit": 20,
    "count": 20,
    "desc": false,
    "items": [
      {
        "id": "eLN5rTB8sYTBWdfzx",
        "userId": "uSeRiDeXaMpLe123",
        "name": "example-scraper",
        "username": "janedoe",
        "title": "Example Scraper",
        "description": "Scrapes example.com",
        "categories": ["ECOMMERCE"],
        "pictureUrl": "https://...",
        "userPictureUrl": "https://...",
        "ownerName": "Jane Doe",
        "ownerImageUrl": "https://...",
        "url": "https://...",
        "readmeSummary": "...",
        "avgRating": 4.5,
        "totalReviews": 12,
        "isUnderMaintenance": false,
        "actorPermissionLevel": "LIMITED_PERMISSIONS",
        "pricingInfos": [{ "pricingModel": "FREE" }],
        "currentPricingInfo": { "pricingModel": "FREE" },
        "stats": {
          "totalRuns": null,
          "totalUsers": null,
          "totalUsers7Days": null,
          "totalUsers30Days": 90,
          "totalUsers90Days": null
        },
        "createdAt": "2026-01-15T10:30:00.000Z",
        "modifiedAt": "2026-08-01T12:00:00.000Z"
      }
    ]
  }
}

stats.totalUsers30Days is the Actor's monthly active users: every distinct user who started a run in the last 30 days. It is the only usage number the Store publishes. Run counts, total users and bookmark counts are not public: the other stats keys are kept for compatibility with existing clients and are always null. Owners see their own Actor's numbers in Insights.

description is truncated to 280 characters.

The list doesn't include the icon itself. Use pictureUrl (null when the Actor has no icon) directly as an image URL. It is versioned by the icon's content and can be cached for a long time (see Get Actor icon and picture).

To bookmark a Store Actor, see Bookmarks.

Store for AI agents

Returns Store entries an AI agent can act on without a second lookup. All the list parameters above work the same way, so an agent can search with search=... and page with limit and offset. Each entry has the Store's standard fields (id, title, name, username, description, notice, badge, categories, stats) plus:

The response also has a usage object with authentication and calling instructions, sent once instead of in every entry.

The agent format only lists Actors whose owners allow AI agents (allowsAgenticUsers, on by default). Sending allowsAgenticUsers=false with responseFormat=agent returns no items.

curl "https://api.scrape.ly/v2/store?responseFormat=agent&search=google%20maps&limit=3"

{
  "data": {
    "total": 4,
    "offset": 0,
    "limit": 3,
    "count": 3,
    "desc": false,
    "items": [
      {
        "id": "eLN5rTB8sYTBWdfzx",
        "title": "Example Scraper",
        "name": "example-scraper",
        "username": "janedoe",
        "actor": "janedoe/example-scraper",
        "description": "Scrapes product listings from example.com. Returns title, price and URL.",
        "purpose": "Scrapes product listings from example.com.",
        "notice": null,
        "badge": null,
        "categories": ["ECOMMERCE"],
        "stats": { "totalUsers30Days": 90 },
        "inputs": [
          { "name": "startUrls", "type": "array of {url}", "required": true, "description": "Category or search pages to scrape.", "example": [{ "url": "https://example.com/shoes" }] },
          { "name": "maxItems", "type": "integer", "required": false, "description": "Stop after this many products.", "example": 50 }
        ],
        "inputExample": { "startUrls": [{ "url": "https://example.com/shoes" }], "maxItems": 50 },
        "outputFields": ["title", "price", "url"],
        "pricing": {
          "model": "PAY_PER_EVENT",
          "summary": "Pay per event: $2.50 per 1,000 results. Plus platform usage (compute, storage, proxy).",
          "events": [{ "event": "scrapely-default-dataset-item", "title": "Result", "priceUsd": 0.0025 }]
        },
        "rating": { "average": 4.5, "count": 12 },
        "health": "ok",
        "run": {
          "api": "POST https://api.scrape.ly/v2/acts/janedoe~example-scraper/run-sync-get-dataset-items",
          "mcp": "call-actor {\"actor\":\"janedoe/example-scraper\",\"input\":{...}}"
        },
        "url": "https://..."
      }
    ],
    "usage": {
      "auth": "Send your Scrape.ly API token as \"Authorization: Bearer $SCRAPELY_TOKEN\".",
      "runApi": "POST the input JSON to an item's run.api URL ...",
      "mcp": "MCP server: https://api.scrape.ly/mcp ...",
      "pricing": "Prices are in USD and are charged to the token owner's prepaid balance."
    }
  }
}

Opting an Actor out

Actors allow AI agents by default. As the owner, turn it off with PUT /v2/actors/{actorId} and { "allowsAgenticUsers": false } (see Update Actor). The Actor then no longer appears in the agent format, and runs paid with an agent payment protocol (x402) return 403 agentic-users-not-allowed. This covers every way to start it: direct runs, saved tasks (also creating one), schedules and automations of x402 wallet accounts, Standby requests, metamorph, and resurrect. Calls with an API token aren't affected, and you can always run your own Actor.

Public Store API

Read-only, unauthenticated endpoints that power the public Store pages. Use them for anonymous browsing, search, and SEO. Responses are cached for up to an hour, so new reviews or stats can take that long to appear.

• No Authorization header is needed (or used).
• Responses carry Cache-Control: public, max-age=300, s-maxage=3600, stale-while-revalidate=86400 and an ETag. Send If-None-Match to get 304 Not Modified.
• All JSON responses are wrapped in data.

Actor cards

Lists and sections return cards with this shape:

{
  "id": "eLN5rTB8sYTBWdfzx",
  "username": "janedoe",
  "name": "example-scraper",
  "title": "Example Scraper",
  "description": "Scrapes example.com",
  "categories": ["ECOMMERCE"],
  "industries": ["e-commerce"],
  "outputTypes": ["products", "prices"],
  "targetSites": ["example.com"],
  "pictureUrl": "https://api.scrape.ly/v2/actors/eLN5rTB8sYTBWdfzx/picture.webp?v=...",
  "ownerName": "Jane Doe",
  "ownerImageUrl": "https://...",
  "stats": { "totalUsers30Days": 90 },
  "rating": { "average": 4.5, "count": 12 },
  "pricing": { "model": "PAY_PER_EVENT", "usdPer1000": 2.5, "unitName": "result" },
  "isUnderMaintenance": false,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "modifiedAt": "2026-08-01T12:00:00.000Z",
  "consoleUrl": "https://scrape.ly/store/janedoe/example-scraper"
}

industries and outputTypes come from fixed lists, targetSites are the domains the Actor scrapes (empty for crawlers that take any site). Search responses also carry facets (industries, outputTypes, sites: { name, count } lists over the other filters), and the overview lists the same counts. description is truncated to 300 characters. pictureUrl is null when the Actor has no icon. pricing.model is FREE or PAY_PER_EVENT; usdPer1000 is the price of 1,000 units of the main event.

Store overview

Returns total (number of public Actors), categories, industries, outputTypes and sites (each [{ "name", "count" }]), sections, and generatedAt. sections has up to 9 cards each:

Search the Store

curl "https://api.scrape.ly/v2/public/store/actors?q=google+maps&pricing=free&limit=10"

Each item is a full card.

Actor page

Everything a public Actor page needs, in one call. Unknown or private Actors return 404 actor-not-found.

Sitemap

Every public Actor as { "username", "name", "title", "modifiedAt" }, plus total and generatedAt. Use it to build sitemaps or sync a catalog.

Example tasks

Every published example task, newest first (at most 10,000), for sitemaps. Each item is { "actorId", "username", "name", "slug", "title", "publishedAt" }, plus total and generatedAt.

Actor picture

Returns a public Actor's current icon, or 404 picture-not-found. The pictureUrl in cards points to /v2/actors/{actorId}/picture.webp?v={hash} instead, which is versioned by the icon's content and cached as immutable.

Reviews

Users who have run a public Actor can rate it 1–5 stars and leave a comment. Reading reviews is public; submitting one requires authentication.

Review stats

curl "https://api.scrape.ly/v2/actors/{actorId}/reviews/stats"

List reviews

Newest first. limit defaults to 20 (max 100); offset defaults to 0.

curl "https://api.scrape.ly/v2/actors/{actorId}/reviews?limit=20&offset=0"

Submit or update a review

Creates your review, or updates your existing one. Returns 201 on create and 200 on update, with { "id", "userId", "username", "rating", "reviewText" } in data.

curl -X POST "https://api.scrape.ly/v2/actors/{actorId}/reviews" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "rating": 5, "reviewText": "Works great" }'

Rules:

• The Actor must be public (403 forbidden).
• You can't review your own Actor (403 forbidden).
• You must have run the Actor at least once (403 run-required).
• If your review was first created less than 24 hours ago, you can't submit or update it yet (429 rate-limited).

Issues

Issues are bug reports, feature requests, and feedback threads on public Actors. Any signed-in user who has run the Actor can open one.

Issues on Actors you own

Owner inbox: issues filed on Actors you own, not issues you opened on other people's Actors.

curl "https://api.scrape.ly/v2/user/issues?status=open&type=bug" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN"

{
  "data": {
    "total": 4,
    "offset": 0,
    "limit": 20,
    "stats": {
      "totalIssues": 10,
      "openIssues": 4,
      "closedIssues": 6
    },
    "items": [
      {
        "id": "issue-uuid",
        "actorId": "eLN5rTB8sYTBWdfzx",
        "actorName": "example-scraper",
        "actorUsername": "janedoe",
        "userId": "user-uuid",
        "username": "reporter",
        "userImageUrl": null,
        "title": "Times out on large URLs",
        "description": "Steps to reproduce...",
        "actorRunUrl": null,
        "status": "open",
        "type": "bug",
        "createdAt": "2026-08-01T12:00:00.000Z",
        "updatedAt": "2026-08-01T12:00:00.000Z",
        "closedAt": null,
        "closedBy": null
      }
    ]
  }
}

stats counts all issues on your Actors, ignoring filters. total and items honor status and type.

Hide the removed-from-store notice

Hides the "Removed from store" notice of your own deprecated Actor from the Issues tab. Returns 200:

{ "data": { "actorId": "eLN5rTB8sYTBWdfzx", "hidden": true } }

Returns 404 actor-not-found if the Actor isn't yours or isn't deprecated.

curl -X POST "https://api.scrape.ly/v2/user/issues/maintenance/eLN5rTB8sYTBWdfzx/hide" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN"

Issue stats for an Actor

Public. Returns open and closed counts for one Actor.

{
  "data": {
    "totalIssues": 10,
    "openIssues": 4,
    "closedIssues": 6
  }
}

List issues for an Actor

Public. Supports status, type, limit (max 100), and offset, the same filters as the owner inbox.

curl "https://api.scrape.ly/v2/actors/{actorId}/issues?status=open&limit=20"

Create an issue

curl -X POST "https://api.scrape.ly/v2/actors/{actorId}/issues" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Actor times out on large URLs",
    "description": "Steps to reproduce...",
    "type": "bug",
    "actorRunUrl": "https://my.scrape.ly/actors/{actorId}/runs/{runId}"
  }'

Returns 201 with the created issue in data. The Actor owner gets a dashboard notification.

Rules:

• The Actor must be public (403 forbidden).
• You can't open an issue on your own Actor (403 forbidden).
• You must have run the Actor at least once (403 run-required).
• One new issue per Actor per 24 hours (429 rate-limited).

The reporter and the Actor owner are subscribed to comment notifications automatically.

Close or reopen

Only the Actor owner can close or reopen an issue. Closing an already-closed issue, or reopening an open one, returns 400 invalid-action. Both return { "data": { "id", "status", "closedAt", "closedBy" } }.

curl -X PATCH "https://api.scrape.ly/v2/actors/{actorId}/issues/{issueId}/close" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN"

Comments

GET is public (limit default 50, max 100). POST requires authentication. DELETE is allowed for the comment author or the Actor owner.

curl -X POST "https://api.scrape.ly/v2/actors/{actorId}/issues/{issueId}/comments" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "body": "I can reproduce this on v1.2.0" }'

• body is required, max 5000 characters, and profanity-filtered.
• Closed issues reject new comments (403 issue-closed).
• The Actor owner and the issue author can always comment. Other users must have run the Actor and can post at most 3 comments per issue per 24 hours (429 rate-limited).
• A new comment sends a dashboard notification to everyone subscribed to the issue with notifyOnComment on.

Issue subscriptions

Authentication required. Subscriptions control comment notifications for one issue.

curl -X PUT "https://api.scrape.ly/v2/actors/{actorId}/issues/{issueId}/subscription" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "notifyOnComment": true }'

GET and PUT return { "data": { "isSubscribed": true, "notifyOnComment": true } }. DELETE unsubscribes and returns { "data": { "success": true } }.

Record a page view

Records a view of an Actor's page for the owner's acquisition analytics. Authentication optional, so anonymous views count. Views are recorded only for public Actors, or by the owner on their own Actor.

curl -X POST "https://api.scrape.ly/v2/actors/{actorId}/pageview" \
  -H "Content-Type: application/json" \
  -d '{"pageType": "detail", "sessionId": "s_8f2c91ab", "referrer": "https://google.com"}'

Returns 201 with { "data": { "recorded": true } }.

Generate sessionId on the client and reuse it for the visitor's session so repeat views aren't counted as new visitors. Owners read the results through the acquisition insight endpoints.

Errors