scrapefield-com Account API

openapi: 3.2.0
info:
  title: ScrapeField Account API
  version: 1.0.0
  summary: One API for Google Maps, LinkedIn, Instagram, TikTok and X.
  description: 'One key, one invoice, five platforms — and each platform''s data in its own shape. A Google Maps place is named the way Google''s Places API names it, an Instagram post the way the Graph API does, a TikTok video the way TikTok''s own APIs do, an X post the way X''s API v2 does; LinkedIn, which has no official data API, uses the words it prints.


    **Conventions.** The same everywhere: the `{ data, meta }` envelope, snake_case, ISO 8601 UTC timestamps, the platform''s own ids as strings, and every documented key present on every object.


    **Pricing.** Every endpoint has a published credit cost, carried here as `x-credits`. Multiply by your volume to get your bill — there are no plans and no tiers, just credits. A call we fail is refunded automatically and the reversal appears in your usage ledger.


    **Pagination.** Cursor only. Pass `meta.next_cursor` back as `cursor`; `null` means the last page. A page holds at most `limit` rows, sometimes fewer; an endpoint without `limit` has a fixed page size, given in its description. A cursor lasts as long as the answer is cached (hours); after that it is refused with `invalid_cursor`.


    **Demo.** Any data endpoint answers with no key when you add `?demo=true`: a fixed answer in the same shape, charged nothing.


    **Nulls.** A field is `null` when the platform does not expose it — never 0 and never a guess.'
  contact:
    name: Support
    url: https://scrapefield.com/contact
    email: support@scrapefield.com
servers:
- url: https://api.scrapefield.com/v1
security:
- bearerAuth: []
tags:
- name: Account
paths:
  /account:
    get:
      operationId: getAccount
      tags:
      - Account
      summary: The balance, the limits and this key
      responses:
        '200':
          description: The account.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - account_id
                    - credits_remaining
                    - concurrency_limit
                    - key
                    properties:
                      account_id:
                        type: string
                      plan:
                        type: string
                      credits_remaining:
                        type: integer
                      credits_granted:
                        type: integer
                      period_start:
                        type: string
                        format: date-time
                      concurrency_limit:
                        type: integer
                        description: Calls this account may have running at once.
                      concurrency_in_use:
                        type: integer
                      key:
                        type: object
                        properties:
                          id:
                            type: string
                          prefix:
                            type: string
                          name:
                            type: string
                          scopes:
                            type: array
                            items:
                              type: string
                            description: The platforms this key may call; empty means all.
                      usage_by_endpoint:
                        type: object
                        description: The newest 500 calls by endpoint, on the platforms this key may call.
                        additionalProperties:
                          type: object
                          properties:
                            calls:
                              type: integer
                            credits:
                              type: integer
                            cached:
                              type: integer
                            refunded:
                              type: integer
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
  /usage:
    get:
      operationId: listUsage
      tags:
      - Account
      summary: 'The usage ledger, newest first: one row a call'
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      responses:
        '200':
          description: Rows on the platforms this key may call.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        ts:
                          type: string
                          format: date-time
                        request_id:
                          type: string
                        endpoint:
                          type: string
                        credits:
                          type: integer
                          description: 0 for a refunded call.
                        refunded:
                          type: boolean
                        credits_refunded:
                          type: integer
                        cached:
                          type: boolean
                        status:
                          type: integer
                        duration_ms:
                          type: integer
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
  /signup:
    post:
      operationId: startSignup
      tags:
      - Account
      summary: Ask for an account and a key for the person you work for
      security:
      - {}
      description: No key needed. We email the person a link; they sign in and type `user_code`, which you show them. Then poll `GET /signup` with `id` as the bearer token. An account an agent starts has no free credits.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: The person's address. The account is theirs.
                agent:
                  type: string
                  maxLength: 60
                  description: 'What you are called, as they know you: shown to them in the email.'
      responses:
        '202':
          description: The request, waiting for the person.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                    - id
                    - user_code
                    - status
                    - expires_at
                    properties:
                      id:
                        type: string
                        description: 'A secret worth a key: send it as the bearer token of `GET /signup`, never in a URL.'
                      user_code:
                        type: string
                        description: 'Show this to the person: they type it to approve you.'
                      status:
                        type: string
                        enum:
                        - pending
                      expires_at:
                        type: string
                        format: date-time
                      retry_after:
                        type: integer
                        description: Seconds to wait between polls.
                      next:
                        type: string
        '400':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
    get:
      operationId: pollSignup
      tags:
      - Account
      summary: Whether the person approved you; the key, once
      description: 'Send the request''s `id` as `Authorization: Bearer sfsu_…`. `approved` carries `api_key` once; later polls say `delivered`.'
      responses:
        '200':
          description: How the request stands.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - status
                    properties:
                      status:
                        type: string
                        enum:
                        - pending
                        - approved
                        - delivered
                        - expired
                        - cancelled
                      api_key:
                        type: string
                        description: With `approved` only, once.
                      key:
                        type: object
                        properties:
                          id:
                            type: string
                          prefix:
                            type: string
                          name:
                            type: string
                      credits_remaining:
                        type: integer
                      expires_at:
                        type: string
                        format: date-time
                      retry_after:
                        type: integer
        '400':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
components:
  schemas:
    error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          - request_id
          properties:
            type:
              type: string
              enum:
              - invalid_request
              - authentication_error
              - method_not_allowed
              - permission_error
              - not_found
              - rate_limit
              - upstream_error
              - not_available
              - internal_error
            code:
              type: string
              description: Stable and documented. Branch on this, not on the message.
              enum:
              - key_in_url
              - missing_api_key
              - invalid_api_key
              - insufficient_credits
              - account_suspended
              - scope_not_allowed
              - fresh_not_available
              - disposable_email
              - signup_rate_limit
              - invalid_link
              - link_used
              - link_expired
              - email_rate_limit
              - sign_in_rate_limit
              - account_closed
              - key_limit
              - unverified_account
              - unknown_endpoint
              - missing_parameter
              - missing_one_of
              - invalid_parameter
              - invalid_json
              - invalid_cursor
              - profile_not_found
              - place_not_found
              - subject_suppressed
              - signup_not_found
              - post_not_found
              - posting_not_found
              - group_not_found
              - ad_not_found
              - community_not_found
              - endpoint_busy
              - concurrency_limit
              - method_not_allowed
              - not_found_limit
              - demo_limit
              - not_available_yet
              - upstream_unavailable
              - internal_error
            message:
              type: string
              description: Written for a human and says what to do next. May change.
            docs:
              type: string
            request_id:
              type: string
            retry_after:
              type: integer
              description: 'On a 429: seconds to wait, as the `Retry-After` header says.'
  responses:
    error:
      description: Something went wrong. `error.code` is stable; `error.message` says what to do next.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer sf_live_…`'