Automate Pulls with the API
Run a RestoreCord member migration with an API key: find your server and destination, estimate, start the pull, watch progress, then pause, resume or stop it.
Everything in the pull popup can be done with an API key: find your server and destination, estimate, start, watch, then pause, resume or stop. This page walks through the calls in order. Full request and response details are in the Migrations API.
All requests go to https://restorecord.com with your key in the Authorization header. See API Keys.
Permissions
| Call | API key permission |
|---|---|
GET /api/v3/servers | READ_SERVERS |
GET /api/v3/bots | READ_BOTS |
GET /api/v3/bots/{botId}/guilds | READ_BOTS |
| Estimate | READ_SERVERS |
| Start, pause, resume, stop | SERVER_PULL |
GET /api/v3/servers/status | READ_SERVERS |
PUT /api/v3/servers/{serverId}/members/{userId} (one member) | SERVER_PULL |
Only keys with SERVER_PULL can start, pause, resume or stop migrations, and only on servers the key's account owns or has Pull Members on. Give pull automation its own key, and set the key's IP allowlist.
Step by Step
Find the source server
GET /api/v3/servers lists your servers. Use the numeric id as serverId in every migration path, and note the server's customBotId.
Find the destination server
GET /api/v3/bots lists your bots. Find the bot whose id equals the server's customBotId, and use its clientId as botId.
GET /api/v3/bots/{botId}/guilds lists the Discord servers that bot is in. Use the destination's id as targetGuildId. If it's missing, invite the bot to that server first.
Pick a role
Use the Discord role ID of the role to give (in Discord, turn on Developer Mode, then right-click the role › Copy Role ID). The role must be below the bot's role. To give no role, send the @everyone role ID (the same as the server ID).
Estimate
GET /api/v3/servers/{serverId}/migrations/estimate?targetGuildId={targetGuildId}count is how many members are eligible after your filters; total is how many still authorize the bot. Add the same filter parameters you plan to start with. Members already in the destination are included in count. Up to 15 estimates per minute.
Start
POST /api/v3/servers/{serverId}/migrations
Content-Type: application/json
{
"targetGuildId": "222222222222222222",
"selectedRoles": ["333333333333333333"],
"customPullCount": 0,
"delayMin": 800,
"delayMax": 800
}customPullCount: 0 means Unlimited: every eligible member is pulled. A 201 response means the migration was created. migration.queued is true if it's waiting behind another migration for this server, and migration.targetMembersUnavailable is true if Server Members Intent is off. Up to 5 starts per minute.
Every option and its plan is in Pull Settings, with the matching field name.
Watch progress
GET /api/v3/servers/statusReturns your active migrations (and those that ended in the last 10 minutes) with status, success, attempted, total and the other counters. Find yours by serverId and targetGuildId, and keep its id for the next step. Poll every few seconds. Once it's gone from the active list, look it up with ?history=true.
On Business and Enterprise, GET /api/v3/servers/{serverId}/migrations/status returns the latest migration for one server with an isActive flag.
Pause, resume or stop
| Action | Request |
|---|---|
| Pause | DELETE /api/v3/servers/{serverId}/migrations?migrationId={id}&action=pause |
| Resume | PATCH /api/v3/servers/{serverId}/migrations?migrationId={id} |
| Stop | DELETE /api/v3/servers/{serverId}/migrations?migrationId={id} |
Pause uses DELETE with action=pause, but it doesn't delete anything: the migration keeps its queue and can be resumed. Without migrationId, pause and stop apply to every active migration for the server. Stopped migrations can't be resumed.
Good Practice for Scripts and AI Agents
- Estimate first. If
countis 0, starting returns No members found for migration. - Check the status, not the response message. A finished migration's
statusisSUCCESS(shown as Finished),FAILEDorSTOPPED. - Respect
429. Wait for theRetry-Afterheader before trying again. - Don't retry a
409. A migration start is already in progress for this server means a start is being processed; check the status instead of starting again. - Don't start duplicates. A second start for the same server is queued behind the first, not merged with it.
- Options your plan doesn't include have no effect. Check Pull Settings before relying on an option.
leaveServermakes your bot leave the destination after a finished migration that reached its pull amount. It doesn't remove members.