users.setUserStatuses

Classify imported source accounts as human, bot, or ai_agent.

Facts


Method	`POST https://yourinstance.getdx.net/api/users.setUserStatuses`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`connection_type`	`String`	The source of the imported user accounts. Applies to every user in the request. Supported values: `github`, `gitlab`, `ado`, `bitbucket`, `bitbucket_server`. Each value matches the prefix of the source’s users table in Data Studio. For example, accounts in `github_users` use `github`, and accounts in `bitbucket_server_users` use `bitbucket_server`.
`users`	`Array<Object>`	1 to 1000 users to classify. The limit counts repeated entries. Each object should contain `source_id` and `status`. `source_id` is the user ID assigned by the source. For example, if `connection_type` is `github`, `source_id` should be the ID assigned by GitHub. `source_id` can be also retrieved with a query of the source’s users table, such as `github_users`, on the Data Studio page of the DX dashboard. `status` is one of `human`, `bot`, or `ai_agent`. Both `bot` and `ai_agent` mark the account as non-human. Example: `[{"source_id": "12345", "status": "bot"}]`

Optional arguments

Name	Type	Description
`instance_url`	`String`	The base URL of the source instance. Scopes the lookup for every user in the request. Find it in the source’s instances table, such as `normalized_instance_url` in `github_instances`. Use the instance’s base URL, not a repository URL. Required when the same `source_id` exists on more than one instance. Ignored for `ado`. For Bitbucket Cloud, use the workspace URL. Example: `https://bitbucket.org/acme`

Usage info

Use this method to classify accounts in bulk. It sets the same classification as Mark users as bots on the Connections page. See How can I mark users as bots?.

DX updates the account’s bot and type columns in the source’s users table, such as github_users. It then updates the account’s pull requests and reviews in the background, so they are marked as bot-authored or not.

Each request covers one connection_type, plus an optional instance_url. To classify accounts from several sources or instances, send one request per source or instance.

Example request

This is a typical request:

curl -X POST https://yourinstance.getdx.net/api/users.setUserStatuses \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -H 'Content-Type: application/json' \
  --data '{
    "connection_type": "github",
    "instance_url": "https://github.com",
    "users": [
      {
        "source_id": "12345",
        "status": "ai_agent"
      },
      {
        "source_id": "67890",
        "status": "bot"
      }
    ]
  }'

Example response

{
  "ok": true,
  "resolved_users": [
    {
      "model": "Github::User",
      "user_id": 101,
      "status": "ai_agent",
      "changed": true,
      "source_id": "12345"
    },
    {
      "model": "Github::User",
      "user_id": 202,
      "status": "bot",
      "changed": false,
      "source_id": "67890"
    }
  ]
}

Common errors

Error	Description
`user_not_found`	No imported user matches a submitted source ID.
`ambiguous_user`	Multiple imported users match a source ID. Supply `instance_url` to narrow the lookup.
`conflicting_statuses`	The same source ID was submitted with different statuses. Repeating a source ID with the same status is allowed, but each entry counts toward the 1,000-entry request limit.