Start a social scan

Find new discussions relevant to this brand, the same scan the “Run a scan” button in the product starts. Every scan surfaces 10 results across the channels you name: 5 on Reddit and 5 on LinkedIn when you pick both, shifting toward one channel only when the other finds fewer worth surfacing. A scan costs 20 credits, refunded per missing result if it comes up short. The brand’s first scan is free.

Only one scan may run per brand per channel at a time. A second call while one is already running is refused, not queued.


POST /brands/{brand_id}/social/scans

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required
`Idempotency-Key`	`string`	required on every write. See Idempotency

Path parameters

Parameter	Type	Required	Description
`brand_id`	`uuid`	required	From List brands

Body parameters

Parameter	Type	Required	Description
`channels`	`string[]`	optional	Any of `reddit`, `linkedin`. Defaults to `["reddit"]`. LinkedIn needs a plan that includes it.
`channel`	`string`	optional	Deprecated: one channel, the same as `channels` with one entry.
`result_count`	`integer`	optional	Deprecated and ignored: every scan surfaces 10 results.

Request

cURL


curl --request POST \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/social/scans' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: 3f9a1c2e-8b4d-4a6f-9c1e-2d5b7a8f9e01' \
  --header 'Content-Type: application/json' \
  --data '{"channels": ["reddit", "linkedin"]}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/social/scans"
 
headers = {
    "Authorization": "Bearer <api-key>",
    "Idempotency-Key": "3f9a1c2e-8b4d-4a6f-9c1e-2d5b7a8f9e01",
    "Content-Type": "application/json",
}
 
response = requests.post(url, headers=headers, json={"channels": ["reddit", "linkedin"]})
 
print(response.text)

JavaScript


const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api-key>',
    'Idempotency-Key': '3f9a1c2e-8b4d-4a6f-9c1e-2d5b7a8f9e01',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ channels: ['reddit', 'linkedin'] }),
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/social/scans', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

PHP


<?php
 
$curl = curl_init();
 
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/social/scans",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode(["channels" => ["reddit", "linkedin"]]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <api-key>",
    "Idempotency-Key: 3f9a1c2e-8b4d-4a6f-9c1e-2d5b7a8f9e01",
    "Content-Type: application/json"
  ],
]);
 
$response = curl_exec($curl);
$err = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Go


package main
 
import (
    "bytes"
    "fmt"
    "net/http"
    "io"
)
 
func main() {
 
    url := "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/social/scans"
    payload := []byte(`{"channels": ["reddit", "linkedin"]}`)
 
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
 
    req.Header.Add("Authorization", "Bearer <api-key>")
    req.Header.Add("Idempotency-Key", "3f9a1c2e-8b4d-4a6f-9c1e-2d5b7a8f9e01")
    req.Header.Add("Content-Type", "application/json")
 
    res, _ := http.DefaultClient.Do(req)
 
    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)
 
    fmt.Println(string(body))
 
}

Ruby


require 'uri'
require 'net/http'
require 'json'
 
url = URI("https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/social/scans")
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <api-key>'
request["Idempotency-Key"] = '3f9a1c2e-8b4d-4a6f-9c1e-2d5b7a8f9e01'
request["Content-Type"] = 'application/json'
request.body = { channels: ["reddit", "linkedin"] }.to_json
 
response = http.request(request)
puts response.read_body

Response

200


{
  "data": {
    "scan_id": "7c9e1f3a-4b2d-4e6f-8a1c-9d3e5b7f2a10",
    "jobs": [
      { "job_id": "7c9e1f3a-4b2d-4e6f-8a1c-9d3e5b7f2a10", "channel": "reddit", "starting_share": 5 },
      { "job_id": "2f8b6d1c-9a3e-4c7b-b5d2-6e1f4a9c3b08", "channel": "linkedin", "starting_share": 5 }
    ],
    "result_count": 10,
    "credit_cost": 20,
    "is_free_scan": false,
    "job_id": "7c9e1f3a-4b2d-4e6f-8a1c-9d3e5b7f2a10",
    "channel": "reddit"
  },
  "request_id": "req_5a3c8d0e2f4b46a1bc9d"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "This brand has no topics. Set up topics and prompts before starting a scan.",
    "request_id": "req_2b6e9c4a1d3f47b8ae5c"
  }
}

401


{
  "error": {
    "code": "token_expired",
    "message": "This API key has expired. Roll it from the API tab on the Connections page to get a replacement.",
    "request_id": "req_8f21c0aa47b1490d2e63"
  }
}

403


{
  "error": {
    "code": "plan_required",
    "message": "LinkedIn discovery is not included in your plan. Upgrade to enable it.",
    "request_id": "req_9d4a7c1e3b5f48d0ac2e"
  }
}

404


{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "request_id": "req_5b0e77d213a94f6a8ce1"
  }
}

409


{
  "error": {
    "code": "conflict",
    "message": "A Reddit scan is already running. Wait for it to finish.",
    "request_id": "req_1e6b3f9a2c4d47e5b8fa"
  }
}

429


{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 24 seconds.",
    "request_id": "req_31c9ba7f0e5d4a118cc2"
  }
}

Response fields

Field	Type	Description
`data.scan_id`	`uuid`	required. The scan; also the first job’s id
`data.jobs`	`object[]`	required. One per channel scanned: `job_id`, `channel` and `starting_share` (5 of 10 with two channels, 10 with one). Pass a `job_id` to Get scan status
`data.result_count`	`integer`	required. Always `10`, the results the whole scan surfaces
`data.credit_cost`	`integer`	required. `20`, or `0` when `is_free_scan` is `true`
`data.is_free_scan`	`boolean`	required
`data.job_id`	`uuid`	required. The first job, for callers written against the one-channel shape
`data.channel`	`string`	required. The first job’s channel
`request_id`	`string`	required. Also returned as the `x-request-id` header. Quote it when contacting support

Errors

Status	Code	When
400	`invalid_request`	A parameter is unknown or malformed. The message names it
400	`invalid_request`	The brand has no topics, or `channels` names no supported channel
401	`invalid_token`	The key is missing, malformed, or does not exist
401	`token_expired`	The key passed its expiry date
401	`token_revoked`	The key was revoked
403	`plan_required`	LinkedIn discovery is not included in this workspace’s plan
403	`quota_exceeded`	Insufficient credits for this scan’s cost
404	`not_found`	The brand does not exist, or this key is not allowed to reach it
409	`conflict`	A scan is already running for this brand on one of the channels named
429	`rate_limited`	Over 300 requests per minute. See the `Retry-After` header

Notes

Only one scan per brand per channel at a time, enforced at the database level. A scan naming both channels starts on both or on neither.

Always 10 results per scan. With two channels each starts at 5. If one finds fewer results worth surfacing, the other covers the gap (6/4 up to 10/0). If the whole scan still lands below 10, the missing results are refunded. Read the split from Get scan status once a job completes.

Credits and free-scan eligibility are always computed server-side. The first scan per brand is free, across channels. Read credit_cost from the response rather than predicting it.

This endpoint only starts the scan. Poll Get scan status with the returned job_id, then read the results from List social discussions once it completes.