Settings V5 (beta)

Read and change the bot settings used for manual collection.

Bot settings are the same as the Bot settings window on screen: the input values, input mode and union that manual collection uses. Changing them does not start a collection.

Endpoints

  • GET /v5/api/bots/{bot_id}/settings Read input values, input mode, Excel file and union
  • PATCH /v5/api/bots/{bot_id}/settings Change only the keys you send (inputs, input_mode, union)
  • PUT /v5/api/bots/{bot_id}/settings/excel Upload an Excel file (multipart)

Read settings

FieldDescription
inputs{ param1: { name, value } }: the current values of the fields the bot uses.
input_modedirect (typed in) or excel (Excel file).
excel_fileThe Excel file in use { name, uploaded_at }, or null.
union{ enabled, target_dataset_id }: whether results accumulate and onto which dataset (null automatically picks the latest dataset).
Example request 
curl 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Example response 200 
{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "bot_id": "8f3a7c1e9b5d24f6",
    "inputs": {
      "param1": {
        "name": "Keyword",
        "value": "sneakers"
      },
      "param2": {
        "name": "Sort",
        "value": "popular"
      }
    },
    "input_mode": "direct",
    "excel_file": null,
    "union": {
      "enabled": false,
      "target_dataset_id": null
    }
  }
}

Change settings

Only the keys you send change. If any key is rejected, nothing is saved. An unknown top-level key gives INVALID_PARAM (the allowed keys are in details.allowed) and sending nothing gives MISSING_PARAM.

  • inputs — { "param1": "value" }. Sending null clears that field.
  • input_mode — direct or excel. excel needs a bot that can use Excel and an uploaded file; without a file it is 422 EXCEL_FILE_REQUIRED.
  • union — { "enabled": true, "target_dataset_id": 239758028 }. target_dataset_id must be a dataset of this bot (otherwise 404 DATASET_NOT_FOUND); null automatically continues the latest dataset.
Example request 
curl -X PATCH 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": {
    "param1": "running shoes"
  }
}'
Example response 200 
{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "bot_id": "8f3a7c1e9b5d24f6",
    "inputs": {
      "param1": {
        "name": "Keyword",
        "value": "running shoes"
      },
      "param2": {
        "name": "Sort",
        "value": "popular"
      }
    },
    "input_mode": "direct",
    "excel_file": null,
    "union": {
      "enabled": false,
      "target_dataset_id": null
    },
    "plans_out_of_sync": [
      {
        "plan_id": "513",
        "name": "주기 3",
        "label": "매일 18:00 (KST)",
        "changes": [
          {
            "key": "param1",
            "name": "Keyword",
            "plan_value": "boots",
            "bot_value": "running shoes"
          }
        ]
      }
    ]
  }
}
Example request 
curl -X PATCH 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "union": {
    "enabled": true,
    "target_dataset_id": 239758028
  }
}'
Example request 
curl -X PATCH 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "input_mode": "direct"
}'

Effect on plans

The plan that follows the bot settings (plan 1) runs with the new values. Plans from plan 2 on, and plans whose conditions you set separately, are not affected.

If some plan falls out of step, plans_out_of_sync in the response tells you: the plans and fields where the changed condition now differs from the plan's own value (plan_value, bot_value). The field is absent for accounts where multiple plans are not open. To align a plan, use copy settings (copy_settings).

Collecting with Excel is not available in v5 yet. A collection request for a bot whose input_mode is excel gives 422 EXCEL_NOT_SUPPORTED_YET. Switch to typed-in input (direct) and collect.

Upload an Excel file

Upload with the single multipart form field file: .xlsx, .xls or .csv, at most 20MB. Both the extension and the file content must match (INVALID_PARAM), and a file that cannot be read as a spreadsheet or is empty gives 422 EXCEL_FILE_UNREADABLE.

The previous file is switched off and the new file becomes the one in use. The response is what we read: rows (row count), columns (column count) and first_row (how the first row maps to the input fields). Uploading does not change the input mode, so switch input_mode to excel to use it.

Example request 
curl -X PUT 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings/excel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'file=@products.xlsx'
Example response 200 
{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "bot_id": "8f3a7c1e9b5d24f6",
    "detected_type": "xlsx",
    "file": {
      "name": "products.xlsx",
      "uploaded_at": "2026-10-04T09:12:00+09:00"
    },
    "rows": 120,
    "columns": 2,
    "first_row": {
      "param1": {
        "name": "Keyword",
        "value": "sneakers"
      },
      "param2": {
        "name": "Sort",
        "value": "popular"
      }
    }
  }
}

Related guides