Start a scrape

Scrape a creator's recent content on one platform. Bills credits per item returned, post-paid.

POST/v1/discover/scrapes

Authorization

bearerAuth

AuthorizationBearer <token>

API token issued from the dashboard (Settings → API Tokens). Sent as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

platform*string

Social platform identifier. X (Twitter) is x. github tracks a repo (owner/repo) or owner (owner) — watched free (daily stars + releases), no paid scrape.

creatorId?string

Existing creator id. Provide this OR creator (exactly one is required).

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

creator?

Find-or-create by platform handle when no creatorId is given (exactly one of the two is required).

maxItems?integer

Most recent items to pull. Billing is per item actually returned, so this is a ceiling.

Default50

Range1 <= value <= 5000

options?

Optional per-platform tuning, mirroring the dashboard's "Advanced" scrape options. Each field applies only to the platform it names and is ignored otherwise.

Response Body

`application/json`

cURL

curl -X POST "https://example.com/discover/scrapes" \  -H "Content-Type: application/json" \  -d '{    "platform": "youtube"  }'

{
  "success": true,
  "scrape": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "platform": "youtube",
    "creatorId": "688ebf54-d343-4104-8711-82c2feac534a",
    "status": "pending",
    "itemCount": -9007199254740991,
    "creditsCharged": 0,
    "error": "string",
    "maxItems": -9007199254740991,
    "createdAt": "2019-08-24T14:15:22Z",
    "startedAt": "2019-08-24T14:15:22Z",
    "completedAt": "2019-08-24T14:15:22Z"
  },
  "creator": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "description": "string",
    "role": "string",
    "status": "string",
    "website": "string",
    "handles": {
      "property1": "string",
      "property2": "string"
    },
    "tags": [
      "string"
    ],
    "isFavorite": true,
    "lastScrapedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z"
  },
  "creatorCreated": true,
  "estimatedMaxCredits": 0
}

{
  "error": "validation_failed",
  "message": "string",
  "issues": null
}

{
  "error": "unauthorized"
}

{
  "error": "validation_failed",
  "message": "string",
  "issues": null
}

{
  "success": false,
  "error": "API key lacks write permission"
}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

402application/json

403application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`