Publish & monetize

Publishing lists your Actor in the Scrape.ly Store, where anyone with an account can find it and run it. You can keep it free or charge per event. You earn 80% of what users pay with purchased credits, and Scrape.ly keeps 20%. Earnings become available 30 days after they're earned (14 days once you're in good standing), and you request a payout by crypto, PayPal, or bank transfer whenever your available balance reaches the minimum. This page covers the listing, review, pricing, charging from your code, earnings, payouts, insights, and the reviews and issues users leave.

Sell an Actor, step by step

Everything is self-serve. The Monetization card on the Actor's Publication tab shows a checklist with each step's status and an action to complete it.

1. Verify your identity. Required to publish any Actor, free or paid. Verify identity opens the identity check (KYC) in a new tab; it takes a few minutes with an ID document. The checklist updates on its own once the check is approved.
2. Accept the Creator Terms. Required before you set paid pricing.
3. Set pay-per-event pricing with the pricing wizard. See Pricing.
4. Make your developer profile public. Required to publish a paid Actor. Use Make public on the checklist or Settings → Profile.
5. Publish to the Store. Most Actors go live right away. Some get a manual review first.
6. Set up payouts: choose crypto, PayPal, or bank transfer and add your statement details. You can do this before or after publishing. Earnings are kept until your payout details are complete. See Payouts.

Before you publish

The platform checks these when you set isPublic: true. A failed check returns 400 publish-validation with the full list in data.checks. The Publish card shows the same checks before you click.

Returns checks (each with id, label, status of pass, warn, or fail, and a message), passed, requiresReview, riskReasons, and the latest publicationReview. It requires your account API key.

The listing

Open your Actor in the dashboard and go to the Publication tab.

The README (.actor/README.md or README.md) becomes the Actor page. A CHANGELOG (.actor/CHANGELOG.md or CHANGELOG.md) is only shown to you: users don't see build history or release notes. Set useful default or prefill values in your input schema. They fill the run form, and the daily test uses them (see Automatic testing).

Click Publish to Store. Most Actors go live immediately. If a review rule matches, the Actor stays private until the review is decided. Once live, it's listed in the dashboard Store at https://my.scrape.ly/store and has a public page at https://scrape.ly/store/<username>/<actor-name>.

Settings that lock once published

While the Actor is public, you can't change Actor Permissions (limited or full). See Security. To change it, unpublish first. The User Build stays editable.

Source code visibility

Source files, the Dockerfile and build logs are hidden from other users by default. Users can still run the Actor. You can hide them at any time, also while the Actor is published.

To make the source public, turn off Hide source files from public in Advanced Settings and type the Actor name to confirm. Anyone can then read every source file, so check first that no secrets are committed. Through the API, send confirmPublicSourceFiles with the Actor name (see Update Actor).

User Build

Users can't pick a build. Every run of your Actor by someone else uses the User Build set in the Publication tab, and they see no build numbers, build history, or build logs. Leave it empty to give users your default build (defaultRunOptions.build, which is latest unless you change it).

You can change the User Build any time, also after publishing. This lets you test a new build yourself while users stay on a stable one. It must be a build tag or number of a successful build; anything else is rejected on save. A version number such as 0.1 is saved as the build number it points to then, so later builds of that version don't reach users until you pick them. While a build is the User Build, you can't delete it; set a different User Build first. Over the API it's the defaultNonOwnerBuild field of Update Actor. New runs use a changed User Build right away; the public Store page can take up to an hour to show its README and input schema.

Status badges

• Under Maintenance shows users a warning before they run the Actor.
• Deprecated marks it as no longer maintained.

Publishing again clears both flags. You can also unpublish at any time from the same tab.

The same fields are available through the API: isPublic, title, description, categories, seoTitle, seoDescription, isDeprecated, isUnderMaintenance, and defaultRunOptions. See the Actors API. Publishing and paid pricing need your account API key. Run tokens, CI tokens, and x402 payments can't change them.

Manual review

Publishing is automatic unless one of these rules matches. Review rules never block publishing. They only hold the Actor for a person at Scrape.ly to check first.

What happens:

1. PUT /v2/actors/:actorId with "isPublic": true returns 200 with isPublic: false and a publicationReview with status pending.
2. The Publication tab shows In review. You can keep editing the Actor, or withdraw the review.
3. You get an email and a dashboard notification when the review is decided.
4. If it's approved, the Actor goes live. If it's rejected, the reason is shown on the Publish card. Fix it and publish again.

Changing pricing on a public Actor can also go to review: when a free Actor gets its first paid pricing and the new-account or prior-takedown rule matches, or when a price rises above the review threshold. Until the review is decided, the current pricing stays live.

DELETE withdraws a pending review and returns 204. With no pending review, it returns 404 review-not-found. Both responses of GET and PUT /v2/actors/:actorId include publicationReview for the owner: id, trigger (publish or pricing_change), status (pending, approved, rejected, or withdrawn), reasons, submittedAt, decidedAt, and decisionReason.

Automatic testing

Scrape.ly tests every published Actor once a day. The test runs your input schema's default and prefill values under an internal account, so you're never billed for it. A test passes when the run succeeds within 5 minutes and the default dataset isn't empty.

• If your schema has no defaults, the Actor isn't tested, and that never counts as a failure.
• After 3 failures in a row, the Actor is marked Under Maintenance and you get a notification.
• A later passing test clears the maintenance flag.
• After 30 days under maintenance, the Actor is deprecated and removed from the Store.

Input presets

Presets are ready-made inputs that users can pick in the Input dropdown, under Examples. Each one also gets a public page on the Store, linked from your Actor's page and listed in the sitemap, so people searching for that use case find your Actor. There are no automatic presets: only the scenarios you mark become presets.

Mark a scenario in .actor/scenarios.json with a preset block:

{
  "scenarios": [
    {
      "name": "search-dentists-austin",
      "input": {
        "searchTerms": ["dentist"],
        "location": "Austin, TX",
        "maxResults": 10,
        "proxyConfiguration": { "useScrapelyProxy": true }
      },
      "preset": {
        "title": "Dentists in Austin, 10 places",
        "description": "Name, rating, phone and website of each practice.",
        "order": 1,
        "slug": "dentists-austin"
      }
    }
  ]
}

The preset input is the scenario's input with these fields taken out:

• proxy settings: proxyConfiguration, a proxy field, any field whose input schema editor is proxy, and any value shaped like a proxy configuration. keepProxy: true keeps them;
• every field marked isSecret in the build's input schema, always;
• the fields listed in omit.

The rest of the scenario (assertions and test settings) is never part of a preset. Scenarios with matrix, rotate, or forceSolverStatus never become presets, nor do inputs left empty after the strip rules or larger than 16 KB. An Actor shows at most 8 presets; an example task with the same input as a preset wins, and the preset is left out.

Presets come from the scenarios file of the build that runs: users get the presets of your User Build, and you see those of your default build. Build the Actor after you change them. The Presets card on the Publication tab lists them, with View page for each public one:

• Hide removes a preset from the dropdown and its public page right away, without a new build; Show brings it back. Both offer Undo.
• May be unreliable marks a preset whose latest automatic test cycle confirmed a failure. Users see the same hint in the dropdown. It clears when the scenario passes again.

Public preset pages exist only for public Actors. A hidden preset's page answers 410 Gone.

PUT takes { "hiddenPresetIds": ["s:<scenario name>", …] } (at most 100) and returns { "data": { "hiddenPresetIds", "presets" } }, where each preset has id, slug, title, description, order, reliability, and hidden. The hidden-presets routes are owner only and need actors:read (GET) or actors:manage (PUT) on a scoped key. input-presets is public and returns the visible examples and presets; see Saved inputs for an Actor.

Pricing

Two pricing models are available:

The dashboard's Set up pricing wizard on the Publication tab walks you through three steps: Actor pricing, Primary event, and Review. It offers two built-in events, and you can add your own:

The primary event is the one the Store shows as your price. To charge per result, use pay per event with scrapely-default-dataset-item as the primary event.

Pricing over the API

Pricing is the first entry of the Actor's pricingInfos:

{
    "pricingInfos": [
        {
            "pricingModel": "PAY_PER_EVENT",
            "primaryEventName": "scrapely-default-dataset-item",
            "pricingPerEvent": {
                "actorChargeEvents": {
                    "scrapely-actor-start": {
                        "eventTitle": "Actor start",
                        "eventPriceUsd": 0.005
                    },
                    "scrapely-default-dataset-item": {
                        "eventTitle": "Result",
                        "eventPriceUsd": 0.001,
                        "discountEnabled": true
                    }
                }
            }
        }
    ]
}

• discountEnabled applies the user's plan Store discount to that event.
• Each event costs at most $100. Event names follow the charging rules.
• Paid pricing needs the current Creator Terms. Without them, PUT returns 403 creator-terms-required with data.currentVersion. A suspended account gets 403 monetization-suspended.

You don't pay your own Actor's event prices when you run it. You only pay platform usage.

When pricing changes take effect

"Paying users" are users other than you who paid an event fee on the Actor in the last 30 days.

Rules for announced changes:

• Users of the Actor are notified when a change is announced, and again for changes that apply immediately on a public Actor.
• You can announce one increase or model change per 30 days. An earlier one returns 409 pricing-change-limited with data.nextAllowedAt. Decreases are allowed at any time.
• While a change is scheduled, any other pricing change returns 409 pricing-change-pending. Cancel the scheduled change first.
• The Monetization card shows the scheduled change, its effective date, and a Cancel change button.

PUT /v2/actors/:actorId returns the outcome as pricingChange, and the Actor includes any open change as scheduledPricingChange:

DELETE cancels a scheduled or in_review change. Other states return 409 pricing-change-not-cancellable.

Charging from your code

Charge a custom event with Actor.charge(). The event has to be defined in your pricing:

import { Actor } from 'scrapely';

await Actor.main(async () => {
    const result = await Actor.charge({ eventName: 'page-scraped', count: 1 });
    if (result.eventChargeLimitReached) {
        await Actor.exit();
    }
});

The result has three fields:

pushData / push_data charges scrapely-default-dataset-item when it's priced, and can also charge a second event per item. Pass the event name as the second argument in JavaScript, or as charged_event_name in Python. The SDK charges before it writes, and drops the items that don't fit in the budget.

If the write fails after the charge was accepted and the SDK knows nothing was stored (the API returned an error, or the connection was never made), it voids the charge and rethrows. A timeout after sending keeps the charge, since the items may have been stored. Voids that can't be confirmed are retried before the next push and at exit.

await Actor.pushData(items, 'page-scraped');

Rules:

• Event names are up to 128 bytes. They start with a letter or digit and contain only letters, digits, ., _, :, and -.
• count is a whole number from 1 to 1,000,000.
• You can't charge scrapely-default-dataset-item or apify-default-dataset-item yourself. The platform counts those.
• On an Actor that isn't pay per event, charge() logs a warning once and charges nothing.
• Locally, outside a platform run, charges aren't sent anywhere.

The SDKs send charges to POST /v2/actor-runs/:runId/charge with an idempotency key, so retries never double-charge. See the JavaScript SDK and Python SDK for details.

The user's budget

Every run has a spending cap, maxTotalChargeUsd. Users set it when they start a run. If they don't, the Actor's defaultRunOptions.minimalMaxTotalChargeUsd applies. The cap covers platform usage (including proxy traffic and LLM gateway requests) and your event charges together:

• The SDK knows the cap (ACTOR_MAX_TOTAL_CHARGE_USD) and stops charging when the budget runs out. The charge API returns 402 charge-limit-exceeded past that point.
• At settlement, accepted event charges are billed first; platform usage is cut so usage plus fees never exceed the cap.

Check eventChargeLimitReached and stop early. Work done after the budget runs out isn't paid for.

Earnings

When a run of your pay-per-event Actor finishes, the platform settles it. You earn 80% of the event fee the user paid with purchased credits, and Scrape.ly keeps 20%.

Store plan discounts reduce the fee first. Platform usage (compute, storage, proxy) isn't shared.

Every earning, clawback, and payout is an entry in your creator ledger. Billing → Payouts → Activity lists them.

Your balance has two parts: pending (earnings still on hold) and available (everything else). The platform moves earnings to available hourly.

Shorter hold in good standing

New earnings are held 14 days instead of 30 once all of these are true:

• you've received at least one paid payout;
• your account is at least 60 days old;
• monetization isn't suspended on your account;
• you have no takedown or rejected review on record.

Each earning keeps the date it was given when it was earned, so the shorter hold applies to earnings recorded after you qualify. Scrape.ly can extend the hold on specific earnings while it looks into suspected fraud or a chargeback.

Your path to the next payout

Billing → Payouts shows where your money is: how much is on hold and when the next part becomes available, what's available now, the date the money you've already earned reaches your method's minimum (or how much more you need), and whether your first payout is capped. It also tells you how many runs of your Actors in the last 30 days were paid with free or promotional credits. Those runs charge the fee but earn you nothing, because only fees paid with purchased credits are shared.

Refunds and chargebacks

When a user's credit purchase is refunded or charged back, the earnings it funded are reversed with a clawback entry, in proportion to the refunded amount. This also applies to earnings from that purchase that settle after the refund.

• While the reversed earning is still pending, the clawback reduces your pending balance. After that, it reduces your available balance.
• Your available balance can go negative. Later earnings offset it before you can request a payout.

Payouts

You request payouts yourself, by crypto, PayPal, or bank transfer, whenever your available balance reaches your method's minimum. Scrape.ly reviews each request and sends it manually. Your identity is already verified when you publish; Scrape.ly can still ask for further checks before a payout.

Set up payouts

Do this from the checklist on the Publication tab or from Billing → Payouts.

1. Verify your email address, if you haven't yet. Use the link in the email you got when you signed up.
2. Choose a payout method and add its destination. See Payout methods.
3. Add your statement details: legal name and address (country, address line 1, and city are required). Add a VAT ID if you have one. These details appear on your statements.

Payout details and the terms can only be read or changed with your account API key or a dashboard session, not with OAuth apps, run tokens, CI tokens, or x402 payments.

Payout methods

Bank transfers carry fixed SEPA or SWIFT fees, so they start at $500.

Crypto payouts are sent in stablecoins or bitcoin on these networks:

The address is checked against the network you pick: the EIP-55 checksum of a mixed-case address for Ethereum, Polygon, and Base, Base58Check for TRON and legacy Bitcoin addresses, bech32 for bc1 addresses, and a 32-byte public key for Solana. Sending to the wrong network loses the funds, so pick the network your wallet or exchange shows for the deposit address.

For a bank transfer, enter an IBAN if your bank has one, otherwise the account number, plus a routing code (ABA routing number, sort code, IFSC, BSB) where your bank uses one. IBANs are checked for the country's length and the check digits. The SWIFT/BIC is optional for an IBAN from a SEPA country and required otherwise.

Your own payout details are shown in full in Billing → Payouts and the payout API. Self-billing statements, the change emails and the destination change log show them masked: the last 4 characters of an IBAN or account number, the start and end of a wallet address, and the first letter of a PayPal email.

Changed destinations wait 72 hours

When you change your payout destination, you can't request a payout to it for 72 hours. Your balance stays available in the meantime. Every change is emailed to your account address, and Billing → Payouts shows when the new destination becomes active. If you didn't make the change, change your password and contact us right away.

Your first destination doesn't wait if you save it while your available balance is below your method's minimum: there's nothing it could pay out yet. It's still emailed to you.

Changing only your statement details, or saving the same destination again, doesn't start the wait. A request that's already pending keeps the destination it was made with.

Request a payout

In Billing → Payouts, click Request payout. The amount defaults to your full available balance; you can enter a smaller one.

The first-payout cap never lowers a payout below the minimum, so a first bank transfer is exactly $500 once your available balance reaches it.

The button is disabled, with the reason next to it, when your account is suspended, your payout details are missing, your destination was changed in the last 72 hours, a request is already pending, or the balance is under your method's minimum (for example "$12.40 more needed for the PayPal minimum ($25).").

The requested amount is reserved right away: it leaves your available balance with a payout entry, so it can't be requested twice. If you cancel a pending request, or Scrape.ly rejects it, the amount returns to your available balance with a payout_reversal entry. You get an email when a request is paid or rejected.

Statements

Each paid request comes with a self-billing statement numbered SCR-<year>-<sequence>. It lists the amount, the payment date and reference, the masked destination, the earnings it covers, and your details at the time it was issued. Find statements in Billing → Payouts → Statements.

Over the API

The creator endpoints require your account API key. Run tokens, CI tokens, and x402 payments can't use them. Payout details, payout requests, and statements also refuse OAuth apps.

The older /v2/earnings endpoints still work and read from the same ledger. See the Earnings API.

Insights

Development → Insights in the dashboard shows three views across your Actors:

• Monetization: revenue, your Actor fees, users' platform usage, total and paying users, cost per result, and a daily breakdown, for one month
• Debugging: success rate and counts of successful, failed, and aborted runs, with average duration. Defaults to the last 30 days
• Acquisition: visitors, views of the Actor page, input form, and runs, and top referring domains

The same data is available per Actor. These routes are owner-only, cached for 5 minutes, and take month as YYYY-MM:

Reviews

Users rate public Actors from 1 to 5 stars, with optional text up to 5,000 characters. A user can review your Actor only after running it at least once, and can submit one review per day. You can't review your own Actor. Ratings appear on the Actor's Reviews tab and in the Store.

Issues

Users can open issues on public Actors from the Actor's Issues tab. Each issue has a title of up to 255 characters, an optional description up to 10,000 characters, an optional run URL, and a type: bug, unexpected, feedback, or feature. A user can open one issue per Actor per day, and can't open issues on their own Actors.

As the owner, you're subscribed to every new issue and get notified about comments. Only you can close or reopen issues. Development → Issues in the dashboard lists issues across all your Actors.

Filter issue lists with status=open or status=closed. Comments are up to 5,000 characters.

Find your Actor in the Store

Search the Store over the API with search, category, pricingModel, username, and sortBy. Results default to 20 per page, with a maximum of 100.

See the Store API.

What's next

• JavaScript SDK: Actor helpers, including Actor.charge()
• Python SDK: Actor helpers
• Earnings API and Store API
• Security: permission levels and secrets