For your AI
Platform Guides

Create Instagram Account Bundles with TokPortal API

Preview an Instagram account bundle and its credit cost before ordering, then configure the account, Reels and carousels with TokPortal API.

Markdown

Create Instagram Account Bundles with TokPortal API

Use platform: "instagram" when creating a TokPortal bundle. The API can create account-only bundles, account-and-video bundles, or videos-only bundles for an existing delivered account.

This guide covers the public contract. It does not promise reach, engagement, account immunity, or any specific platform outcome.

If you want to launch accounts without writing API calls, open the account order form. Choose Instagram and an available market in the app, then review the cost before ordering. For a US launch from abroad, use the launch guide and planning brief.

1. Preview an Instagram bundle and its cost

First check which countries accept new Instagram accounts. The public endpoint needs no API key:

curl "https://app.tokportal.com/api/ext/countries?platform=instagram"

Choose a country from data, the new-account list. A country present only in videos_only_countries cannot be used for a new account. The US request below is an example, not a guarantee of current availability.

Set TOKPORTAL_API_KEY locally to your own key from API Keys. Then simulate the same account and three video slots you intend to order:

curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: $TOKPORTAL_API_KEY" \
  -H "X-TokPortal-Dry-Run: true" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_type": "account_and_videos",
    "platform": "instagram",
    "country": "US",
    "title": "US Instagram launch",
    "videos_quantity": 3,
    "external_ref": "ig-launch-us"
  }'

Check the successful response before continuing:

  • dry_run is true and credits_charged is 0.
  • credits_would_charge and cost_breakdown show the current quote for your workspace. A zero quote is possible when an allowance applies.
  • data.bundle_id starts with 00000000-0000-4000-8000-. It is synthetic: no account or order has been created.

If you only need an account, use bundle_type: "account_only" and omit videos_quantity. To try the later writes without placing an order, keep the dry-run header on every write and follow the sandbox workflow rules. Simulations do not persist account configuration or uploaded media.

Confirm the quote, then create the real bundle

Bundle creation charges credits immediately. After you approve the scope and current cost, repeat the creation request without X-TokPortal-Dry-Run. Keep the data.bundle_id from that real response for the steps below; never reuse a synthetic ID in a live request.

The real response includes data.bundle_id, credits_charged, credits_remaining, and cost_breakdown. The remaining examples describe real operations. Replace bnd_abc123 with your real bundle ID, use your own media, and review each operation before running it. If your goal was only to evaluate the price, stop after the preview.

Reference: Create Bundle

2. Configure the account profile

Account configuration is required before publishing.

curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/account \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mybrand.us",
    "visible_name": "My Brand",
    "biography": "New drops every week.",
    "profile_picture_url": "https://cdn.example.com/mybrand/profile.jpg",
    "link_in_bio": "https://example.com"
  }'

For Instagram, link_in_bio is supported; on any other platform it is accepted, stored as null, and reported back in the response's _warnings array. biography is capped at 120 characters on Instagram (80 elsewhere). Use unique usernames and display names across accounts.

Reference: Account Configuration

3. Configure an Instagram Reel

For a Reel video, use video_type: "video" and instagram_content_type: "reel".

curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/videos/1 \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "video_type": "video",
    "instagram_content_type": "reel",
    "description": "Morning routine with the new collection #style",
    "target_publish_date": "YYYY-MM-DD",
    "video_url": "https://cdn.example.com/reels/reel-01.mp4",
    "instagram_audio_name": "Original audio",
    "external_ref": "ig-reel-01"
  }'

video_url can be any public/direct URL or a public_url returned by Media Upload. Every Instagram slot that is not a story requires instagram_content_type.

Replace YYYY-MM-DD with a future date before sending either media example. target_publish_date is the first day of a two-day publishing window, with a minimum lead time in UTC of today + 3 days while the account is still being created and today + 1 once the account is delivered or when the bundle runs on an existing account; an earlier date is rejected with INVALID_DATE carrying earliest_allowed. A bundle takes at most 3 videos per day (VIDEOS_PER_DAY_EXCEEDED beyond that).

4. Configure an Instagram carousel post

For a swipeable Instagram carousel, use video_type: "carousel" and instagram_content_type: "post".

Upload images first and use the returned storage_path values:

curl -X POST https://app.tokportal.com/api/ext/upload/image/from-url \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cdn.example.com/carousel/slide-1.jpg",
    "bundle_id": "bnd_abc123",
    "purpose": "carousel"
  }'

Then configure the slot:

curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/videos/2 \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "video_type": "carousel",
    "instagram_content_type": "post",
    "description": "Which look is your favorite?",
    "target_publish_date": "YYYY-MM-DD",
    "carousel_images": [
      "carousel-images/org_xxx/bnd_abc123/slide-1.jpg",
      "carousel-images/org_xxx/bnd_abc123/slide-2.jpg"
    ],
    "instagram_location": "Los Angeles, California"
  }'

Reference: Configure Videos

Advanced Niche Warming

Advanced Niche Warming is the warming product. Send wants_advanced_warming: true together with advanced_warming_terms: 3-30 niche targets, the count a multiple of 3, each 2-50 characters. The flag is mandatory and never inferred, so targets sent without it are rejected with ADVANCED_WARMING_FLAG_REQUIRED and nothing is charged; duplicate or out-of-range targets fail the call with ADVANCED_WARMING_TERMS_REJECTED rather than being silently dropped. The standard rate is 5 credits per target (per target, never per day) and GET /credit-costs returns the effective workspace rate. The manager searches each target while screen-recording, and every recording is verified into a client report. See Advanced Warming.

If the targets are not decided yet, buy them with advanced_warming_terms_count (3-30, multiple of 3) and set them later with PUT /bundles/{id}/warming-terms. Never send both with disagreeing quantities: that fails with ADVANCED_WARMING_COUNT_MISMATCH. Unconfigured purchases are auto-cancelled and fully refunded after 14 days.

curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_type": "account_and_videos",
    "platform": "instagram",
    "country": "US",
    "videos_quantity": 3,
    "wants_advanced_warming": true,
    "advanced_warming_terms": ["street style outfits", "capsule wardrobe", "outfit inspo daily"],
    "external_ref": "ig-advanced-warming-us"
  }'

With 3 targets, warming adds 3 x 5 = 15 credits to the 32 for the account and 2 per video slot, so this bundle is 32 + (3 x 2) + 15 = 53 credits.

This is a standard-rate example. Add X-TokPortal-Dry-Run: true to the creation request to inspect your current workspace quote before approving a real order.

Legacy footnotes, for workspaces still holding older orders: wants_deep_warming: true on a new order is rejected with DEEP_WARMING_DEPRECATED, wants_niche_warming still requires niche_warming_instructions, and it cannot be combined with wants_advanced_warming (WARMING_CONFLICT).

Bulk Instagram creation

POST /bundles/bulk accepts one country and one or more platforms. To cover several countries, call it once per country.

curl -X POST https://app.tokportal.com/api/ext/bundles/bulk \
  -H "X-API-Key: sk_your_key_here" \
  -H "Idempotency-Key: ig-bulk-us-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["instagram"],
    "country": "US",
    "accounts_count": 5,
    "upload_accounts_count": 2,
    "videos_per_account": 6,
    "wants_advanced_warming": true,
    "advanced_warming_terms": ["street style outfits", "capsule wardrobe", "outfit inspo daily"],
    "external_ref": "ig-bulk-us"
  }'

This creates 5 Instagram bundles in the selected country. Two include video slots; three are account-only. The 3 warming targets are applied to every account, so warming is 3 x 5 = 15 credits per account: 5 x 32 for the accounts, plus 5 x 15 for warming, plus 2 x 6 x 2 for the video slots = 259 credits.

This is a standard-rate example, not a workspace quote. Add X-TokPortal-Dry-Run: true to this bulk request and review the returned total before approving all five accounts. Do not turn an account-only preview into a bulk order without reviewing the new scope and cost.

Reference: Create Bulk

Delivered account access

After delivery, accounts are available through the Delivered Accounts API:

curl -X GET "https://app.tokportal.com/api/ext/accounts?platform=instagram" \
  -H "X-API-Key: sk_your_key_here"

Credential reveal is a separate, irreversible endpoint. A saved account created before the immutable production cutoff keeps the prior 0-credit policy and existing task access, while support and ban coverage end after access. An account created at or after the cutoff costs 150 credits unless an admin-approved Account Owning Fee agreement applies, and the current policy permanently detaches it. Pending Owning Fee approval keeps the 150-credit path available; after approval, reveal activates or uses the stored $10 legacy or $15 new per-30-day rate instead. For a new-policy account, first call the endpoint to receive HTTP 428 and the current policy version, then explicitly accept that exact version as described in Delivered Accounts:

curl -X POST https://app.tokportal.com/api/ext/accounts/acc_abc123/reveal-credentials \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"acknowledge_support_forfeit":true,"policy_version":"VERSION_RETURNED_BY_428"}'

Do not send Idempotency-Key to this secret-returning endpoint. On CREDENTIAL_REVEAL_QUOTE_CHANGED, request and display a fresh policy preview before asking for new confirmation.

Related docs: Media Upload, Publish & Unpublish, Analytics, MCP Server.