> ## Documentation Index > Fetch the complete documentation index at: https://docs.alura.io/llms.txt > Use this file to discover all available pages before exploring further. # Start a sync > Asks Alura to sync your connected Etsy shops now (default every shop; `shop_id` for one), for example after you changed prices on Etsy. Answers at once with one outcome per shop: `queued` (a sync started), `already_running` (one was already queued or running; it is returned and not sped up), `cooldown` (with `next_allowed_at`), `reconnect_required` (with `reconnect_url`) or `unavailable` (retry). Each shop can be synced again once its plan allows: Free every 24 hours, Basic 6 hours, Growth 1 hour, Professional 15 minutes, counted from the end of its last sync (scheduled, from the app or through the API). A workspace starts at most 4 syncs per connected shop per UTC day through the API. Follow a sync with GET /v1/workspace/syncs/{id}. Costs 1 API credit per call that queued or found a sync. When every shop is refused it is free: 429 `sync_cooldown` with Retry-After, 409 `reconnect_required` when every shop needs reconnecting, or 503 when Alura could not start any. `Idempotency-Key` is accepted and stores nothing: a repeated call finds the running sync (`already_running`) and costs 1 API credit again. A shop outside the workspace is 404. Cost: 1 API credit per call. ## OpenAPI ````yaml /openapi.json post /v1/workspace/syncs openapi: 3.1.0 info: title: Alura API version: 1.0.0 description: Etsy market research for scripts and AI assistants. servers: - url: https://api.alura.io security: - apiKey: [] paths: /v1/workspace/syncs: post: summary: Start a sync description: >- Asks Alura to sync your connected Etsy shops now (default every shop; `shop_id` for one), for example after you changed prices on Etsy. Answers at once with one outcome per shop: `queued` (a sync started), `already_running` (one was already queued or running; it is returned and not sped up), `cooldown` (with `next_allowed_at`), `reconnect_required` (with `reconnect_url`) or `unavailable` (retry). Each shop can be synced again once its plan allows: Free every 24 hours, Basic 6 hours, Growth 1 hour, Professional 15 minutes, counted from the end of its last sync (scheduled, from the app or through the API). A workspace starts at most 4 syncs per connected shop per UTC day through the API. Follow a sync with GET /v1/workspace/syncs/{id}. Costs 1 API credit per call that queued or found a sync. When every shop is refused it is free: 429 `sync_cooldown` with Retry-After, 409 `reconnect_required` when every shop needs reconnecting, or 503 when Alura could not start any. `Idempotency-Key` is accepted and stores nothing: a repeated call finds the running sync (`already_running`) and costs 1 API credit again. A shop outside the workspace is 404. Cost: 1 API credit per call. operationId: workspace.syncs.start parameters: [] requestBody: required: false content: application/json: schema: type: object properties: shop_id: description: >- Only this connected shop; default every connected shop of the workspace. A shop outside the workspace is 404. type: string pattern: ^[0-9]{1,20}$ additionalProperties: false example: shop_id: '22841907' responses: '202': description: 'Accepted: the work has started and goes on after this answer.' headers: Request-Id: $ref: '#/components/headers/Request-Id' Alura-Credits-Cost: $ref: '#/components/headers/Alura-Credits-Cost' Alura-Credits-Remaining: $ref: '#/components/headers/Alura-Credits-Remaining' Location: description: Where to follow the work, when it can be followed. schema: type: string Retry-After: description: Seconds to wait before following it, when known. schema: type: integer content: application/json: schema: type: object properties: object: type: string const: workspace.sync_start shops: type: array items: type: object properties: shop_id: type: string description: Etsy ID, as a string. outcome: type: string description: >- `queued` (a sync was started), `already_running` (a sync was already queued or running: `sync` is that one), `cooldown` (synced too recently, or the workspace used its daily syncs: see `next_allowed_at`), `reconnect_required` (the shop's Etsy connection has ended: see `reconnect_url`), or `unavailable` (Alura could not start it right now; retry). New values may be added. sync: anyOf: - type: object properties: object: type: string const: workspace.sync id: type: string description: '`syn_` + the sync''s number.' shop_id: type: string description: The connected shop it syncs. status: type: string description: >- `queued`, `running`, `succeeded`, `failed`, `skipped`, or `unknown` (a status Alura does not know yet). New values may be added. trigger: type: string description: >- Who started it: `api` (the API or an AI agent through Alura), `app` (someone clicking Update in Alura), `scheduled` (Alura's regular syncs), `webhook` (an Etsy notification), or `other`. New values may be added. progress: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' description: >- The share of its steps that have ended, 0 to 1: 0 while queued, 1 once it ended; null while running when Alura has no progress for it, and when its status is `unknown`. steps: type: array items: type: object properties: name: type: string description: >- The data the step syncs: settings, listings, orders, reviews, finances, customers. New steps may be added. status: type: string description: >- `pending` (not started), `running`, `succeeded`, `failed`, `not_run` (the sync ended without running it, for example after an earlier step failed), or `unknown` (Alura has no record of it, or the sync's status is `unknown`). New values may be added. required: - name - status additionalProperties: false description: Each step and how far it got. requested_at: type: string description: When it was asked for. started_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: When it started; null while queued. completed_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: When it ended; null until then. estimated_ready_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When it is expected to end; null when unknown (always, for now). error: anyOf: - type: object properties: code: type: string description: >- `reconnect_required` (the shop's Etsy connection has ended), `sync_timed_out`, or `sync_failed`. New codes may be added. message: type: string required: - code - message additionalProperties: false - type: 'null' description: >- Why it failed; null unless it failed or was skipped. required: - object - id - shop_id - status - trigger - progress - steps - requested_at - started_at - completed_at - estimated_ready_at - error additionalProperties: false - type: 'null' description: >- The sync started or already running; null otherwise, or when Alura could not read it back right now. next_allowed_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- With `cooldown`: when a sync of this shop can next be started. reconnect_url: description: >- With `reconnect_required`: where the shop is reconnected. type: - string - 'null' required: - shop_id - outcome - sync - next_allowed_at - reconnect_url additionalProperties: false description: One outcome per shop. notices: type: array items: type: object properties: code: type: string description: >- `stale_shops`, `sales_not_covered`, `partial_range`, `settings_not_fetched`, `settings_sections_only`, `listings_count_unavailable`, `listings_not_synced`, `shipping_cost_inexact` or `sync_daily_cap_reached`. New codes may be added. shop_ids: type: array items: type: string description: The shops the notice is about. detail: type: string required: - code - shop_ids - detail additionalProperties: false description: >- `sync_daily_cap_reached`: the workspace started its most syncs through the API for the UTC day. required: - object - shops - notices additionalProperties: false example: object: workspace.sync_start shops: - shop_id: '22841907' outcome: queued sync: object: workspace.sync id: syn_9004 shop_id: '22841907' status: queued trigger: api progress: 0 steps: - name: settings status: pending - name: listings status: pending - name: orders status: pending - name: reviews status: pending - name: finances status: pending - name: customers status: pending requested_at: '2026-10-17T12:00:00.000Z' started_at: null completed_at: null estimated_ready_at: null error: null next_allowed_at: null reconnect_url: null notices: [] '400': $ref: '#/components/responses/Problem400' '401': $ref: '#/components/responses/Problem401' '402': $ref: '#/components/responses/Problem402' '403': $ref: '#/components/responses/Problem403' '404': $ref: '#/components/responses/Problem404' '405': $ref: '#/components/responses/Problem405' '429': $ref: '#/components/responses/Problem429' '500': $ref: '#/components/responses/Problem500' '503': $ref: '#/components/responses/Problem503' x-codeSamples: - lang: bash label: cURL source: |- curl -X POST "https://api.alura.io/v1/workspace/syncs" \ -H "Authorization: Bearer $ALURA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"shop_id":"22841907"}' - lang: typescript label: TypeScript source: |- const res = await fetch('https://api.alura.io/v1/workspace/syncs', { method: 'POST', headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "shop_id": "22841907" }), }); console.log(await res.json()); - lang: python label: Python source: |- import json import os import urllib.request request = urllib.request.Request( "https://api.alura.io/v1/workspace/syncs", method="POST", data=json.dumps({ "shop_id": "22841907" }).encode(), headers={ "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}", "Content-Type": "application/json", }, ) with urllib.request.urlopen(request) as response: print(json.load(response)) components: headers: Request-Id: description: '`req_` + ULID; quote it when reporting a problem.' schema: type: string Alura-Credits-Cost: description: API credits this call cost. schema: type: integer Alura-Credits-Remaining: description: >- API credits left in the workspace's monthly allowance, counting calls still in flight. Absent when it cannot be read right now. schema: type: integer responses: Problem400: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/invalid_request title: Invalid request status: 400 code: invalid_request detail: Invalid request suggestion: Fix the request as the detail says, then send it again. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem401: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/unauthorized title: Unauthorized status: 401 code: unauthorized detail: Unauthorized suggestion: 'Send a valid API key as `Authorization: Bearer alura_sk_...`.' retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem402: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_exhausted title: API credits exhausted status: 402 code: credits_exhausted detail: API credits exhausted suggestion: Upgrade the plan or wait for the monthly reset. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem403: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/plan_required title: Plan required status: 403 code: plan_required detail: Plan required suggestion: Upgrade the workspace plan to use this operation. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem404: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/not_found title: Not found status: 404 code: not_found detail: Not found suggestion: Check the ID, or search for it first. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem405: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/method_not_allowed title: Method not allowed status: 405 code: method_not_allowed detail: Method not allowed suggestion: Use one of the methods in the Allow header. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem429: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/rate_limited title: Rate limited status: 429 code: rate_limited detail: Rate limited suggestion: Wait for Retry-After, then retry. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem500: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/internal_error title: Internal error status: 500 code: internal_error detail: Internal error suggestion: Retry; if it keeps failing, report the request_id. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem503: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_unavailable title: API credits unavailable status: 503 code: credits_unavailable detail: API credits unavailable suggestion: Retry shortly. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B schemas: Problem: type: object description: RFC 9457 problem details. properties: type: type: string format: uri title: type: string status: type: integer code: type: string description: A code from the error catalog; new codes may be added. x-extensible-enum: - invalid_request - unknown_parameter - invalid_cursor - cursor_window_exceeded - invalid_reference - id_type_mismatch - invalid_keyword - shop_id_required - sales_window_not_covered - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - browser_refused - role_required - impersonation_refused - recent_sign_in_required - etsy_scope_required - etsy_partner_required - not_found - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - reconnect_required - listing_busy - shop_create_busy - idempotency_partial_unverifiable - activation_skipped - idempotency_processing - unprocessable - listing_removed_on_etsy - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - sync_cooldown - shop_write_budget_exhausted - internal_error - write_misconfigured - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - create_lock_unavailable - etsy_capacity - upstream_timeout detail: type: string suggestion: type: string retryable: type: boolean request_id: type: string upgrade_url: type: string format: uri description: 'credits_exhausted and plan_required: where to upgrade the plan.' credits_needed: type: integer description: 'API credit refusals: what the call needed.' credits_remaining: type: integer description: >- API credit refusals: what is left (of the month, or of the day for daily_credit_cap_exceeded). resets_at: type: string format: date-time description: >- credits_exhausted and daily_credit_cap_exceeded: when the limit resets. required: - type - title - status - code - detail - suggestion - retryable - request_id securitySchemes: apiKey: type: http scheme: bearer description: 'An API key: `Authorization: Bearer alura_sk_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.