TraderExportJob

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/0xinsider-com/json-schema/0xinsider-com-trader-export-job-schema.json",
  "title": "TraderExportJob",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/0xinsider-com-openapi.json#/components/schemas/TraderExportJob",
  "type": "object",
  "required": [
    "object",
    "data",
    "meta"
  ],
  "properties": {
    "object": {
      "type": "string",
      "const": "trader_export_job"
    },
    "data": {
      "type": "object",
      "required": [
        "job_id",
        "status",
        "format",
        "total_trades",
        "processed_trades",
        "file_size",
        "error",
        "terminal",
        "next_action",
        "created_at",
        "started_at",
        "ready_at",
        "failed_at",
        "expires_at",
        "expired_at",
        "data_as_of",
        "cancel_requested_at",
        "cancelled_at",
        "attempt",
        "max_attempts"
      ],
      "properties": {
        "job_id": {
          "type": "integer",
          "format": "int64"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "running",
            "ready",
            "failed",
            "reconcile_required",
            "expired",
            "cancel_requested",
            "cancelled"
          ],
          "description": "queued: waiting for a worker. A running job reads queued again, with error saying why, when its worker restarts for a deploy (the next worker claims it within seconds) or stops without handing it back (requeued within a minute of its 30-minute lease lapsing); it starts again from the beginning. running: the worker is streaming rows. reconcile_required: the upload finished but the storage completion answer was lost; the reconciler reads the object back within a minute, retries a failed readback an hour later, and moves the job to ready or failed, and expires_at bounds the wait. ready: downloadable until expires_at. failed: terminal; error says why; submit a new export. expired: the retention window passed; the file is retired, the download route answers 410, submit a new export. cancel_requested: the owner cancelled a running job (POST /api/v1/trader/{address}/export/cancel); the worker stops at its next safe point and the job reads cancelled. cancelled: terminal; the owner cancelled the job and no file was published; submit a new export. A job that has not reached ready by expires_at reads failed with error 'export expired before completion'. failed, cancelled and expired rows stay readable for 48 hours, then the job answers 404."
        },
        "format": {
          "type": "string",
          "enum": [
            "json",
            "ndjson",
            "csv"
          ]
        },
        "total_trades": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "Trade rows the file holds: trades in the wallet's sports and esports markets, counted in the file's own read snapshot. Null until the worker has read the snapshot (queued, and early in running); a job accepted before 2026-10-22 can carry the earlier all-markets estimate until its file is read."
        },
        "processed_trades": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "Trade rows written so far; equals total_trades once the file is read."
        },
        "file_size": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64"
        },
        "error": {
          "type": [
            "string",
            "null"
          ]
        },
        "terminal": {
          "type": "boolean",
          "description": "True when status never changes again (ready, failed, expired, cancelled). Stop polling."
        },
        "next_action": {
          "type": "string",
          "enum": [
            "poll",
            "download",
            "resubmit"
          ],
          "description": "What to do next: poll the status route after poll_after_s, follow the download route, or submit a new export. Published beside status so a status value added later does not strand a client."
        },
        "poll_after_s": {
          "type": "integer",
          "description": "Seconds to wait before polling again. Absent when terminal. 5 while queued, running or cancel_requested; 300 while reconcile_required, the cadence that state can change at."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "started_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the worker last claimed the job; null while queued."
        },
        "ready_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the file became downloadable. null before ready, and on jobs finalized before this field existed."
        },
        "failed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "The retention window: 24 hours from submit. A ready file downloads until this instant; a job that has not reached ready by it fails. A reused job (200 on submit) keeps its original window."
        },
        "expired_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the job became expired; null until then."
        },
        "data_as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "What the file is a snapshot of: the trader's served-data clock (the latest position refresh, else the last completed sync) when the file was written; the same value as export_metadata.data_as_of inside the file. null until the file is written, or when the trader had neither. Read this, not ready_at, to decide whether a reused job is fresh enough; submit with fresh=true for a newer snapshot."
        },
        "cancel_requested_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the owner asked to cancel the job; null otherwise. Set on every cancelled job, including one cancelled while queued. While status is cancel_requested this is the instant the worker was asked to stop."
        },
        "cancelled_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the job reached cancelled; null until then."
        },
        "attempt": {
          "type": "integer",
          "description": "Worker claims so far. A claim handed back when its worker restarts for a deploy is not counted, so attempt steps back by one when the job reads queued again for that reason."
        },
        "max_attempts": {
          "type": "integer",
          "description": "The job fails when attempt reaches this."
        },
        "artifact": {
          "type": "object",
          "description": "Present only while status is ready: the stored object's identity, so a client can check the download it receives.",
          "required": [
            "artifact_id",
            "etag",
            "compressed_size_bytes",
            "content_type",
            "content_encoding",
            "manifest"
          ],
          "properties": {
            "artifact_id": {
              "type": "string",
              "description": "Stable identity for this completed export artifact; unchanged when a temporary download URL is renewed."
            },
            "etag": {
              "type": [
                "string",
                "null"
              ],
              "description": "The storage ETag of the object."
            },
            "compressed_size_bytes": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "Bytes on the wire (gzip); file_size is the decompressed size."
            },
            "content_type": {
              "type": "string",
              "enum": [
                "application/json",
                "application/x-ndjson",
                "text/csv"
              ]
            },
            "content_encoding": {
              "type": "string",
              "const": "gzip"
            },
            "manifest": {
              "oneOf": [
                {
                  "$ref": "#/$defs/TraderExportArtifactManifest"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Immutable manifest for artifacts generated with manifest support; null on historical artifacts written before this contract."
            }
          }
        }
      }
    },
    "meta": {
      "$ref": "#/$defs/ResponseMeta"
    }
  },
  "$defs": {
    "ResponseMeta": {
      "type": "object",
      "required": [
        "request_id",
        "cached",
        "cost"
      ],
      "properties": {
        "request_id": {
          "type": "string",
          "description": "Unique request ID (req_ prefix). The same value as the X-Request-Id response header, the request's usage accounting row and its log lines."
        },
        "cached": {
          "type": "boolean"
        },
        "cache_age_s": {
          "type": "integer",
          "description": "Cache age in seconds. Omitted when the response was not cached, and also when it was cached but its age cannot be established (an entry stored before its cache carried a computed instant). Never a placeholder: an unknown age is reported as no value rather than as the cache TTL."
        },
        "cost": {
          "type": "integer",
          "description": "Advisory request weight (relative compute cost). 1 for simple reads; higher for heavier endpoints. Not a credit/price."
        },
        "ranking_generation": {
          "type": "integer",
          "description": "Committed PostgreSQL-owned leaderboard generation for the returned rows and cursor. Present on GET /api/v1/leaderboard; omitted on endpoints that do not read this ranking."
        },
        "ranking_as_of": {
          "type": "string",
          "format": "date-time",
          "description": "Authoritative RFC3339 timestamp from cache_generations.updated_at for ranking_generation. It is read in the same repeatable-read snapshot as the leaderboard rows and is not request time, cache write time, or row insertion order."
        },
        "directional_source": {
          "type": "string",
          "enum": [
            "live",
            "degraded"
          ],
          "description": "Directional evidence provenance for Edge Hunter signals collections. The default board carries this provenance in data.directional_source and omits this optional meta field."
        },
        "ranking_source": {
          "type": "string",
          "enum": [
            "live",
            "db_only"
          ],
          "description": "Ranking evidence provenance for Edge Hunter signals collections. The default board carries this clock/provenance in data.ranking_source and omits this optional meta field."
        },
        "category_skill_source": {
          "type": "string",
          "enum": [
            "live",
            "partial",
            "degraded",
            "unavailable"
          ],
          "description": "Whole filtered snapshot category-evidence status before pagination. Operational live always remains partial source coverage."
        },
        "category_skill_model_version": {
          "type": "string"
        },
        "category_skill_taxonomy_version": {
          "type": "string"
        },
        "category_skill_platform": {
          "type": "string",
          "const": "polymarket"
        },
        "category_skill_scope": {
          "type": "string",
          "const": "observed_goldsky_primary_taker_fill"
        },
        "category_skill_source_coverage": {
          "type": "string",
          "enum": [
            "partial_whale_threshold_fills",
            "graded_wallet_fills"
          ]
        },
        "category_skill_observation_started_at": {
          "type": "string",
          "format": "date-time"
        },
        "category_skill_model_operationally_degraded": {
          "type": "boolean",
          "description": "Whole-model operational readiness captured with the category model snapshot. Present on category-enriched responses even when the filtered signal list is empty. When true, category_skill_source is degraded and Edge Hunter signals uses the shorter degraded cache TTL."
        },
        "category_skill_status_counts": {
          "type": "object",
          "required": [
            "live",
            "insufficient",
            "stale",
            "unknown",
            "degraded"
          ],
          "properties": {
            "live": {
              "type": "integer",
              "minimum": 0
            },
            "insufficient": {
              "type": "integer",
              "minimum": 0
            },
            "stale": {
              "type": "integer",
              "minimum": 0
            },
            "unknown": {
              "type": "integer",
              "minimum": 0
            },
            "degraded": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "category_skill_base_payload_hash": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "SHA-256 of the funded signal membership/order/rank/cursor vector immediately before category-skill enrichment. Edge Hunter signals view only."
        },
        "category_skill_enriched_base_payload_hash": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "Independent SHA-256 recomputation over the same base fields immediately after category-skill enrichment. Equality with category_skill_base_payload_hash proves category-skill enrichment did not change funded inputs. Edge Hunter signals view only."
        }
      }
    },
    "TraderExportArtifactManifest": {
      "type": "object",
      "required": [
        "manifest_version",
        "format",
        "schema_version",
        "coverage",
        "generation",
        "row_count",
        "content_size_bytes",
        "content_sha256",
        "compressed_size_bytes",
        "compressed_sha256"
      ],
      "properties": {
        "manifest_version": {
          "type": "string",
          "description": "Version of the artifact manifest contract."
        },
        "format": {
          "type": "string",
          "enum": [
            "json",
            "ndjson",
            "csv"
          ],
          "description": "Serialization used for the decompressed content."
        },
        "schema_version": {
          "type": "string",
          "enum": [
            "trader-export-json-v1",
            "trader-export-ndjson-v1",
            "trader-export-csv-v1"
          ],
          "description": "Stable schema identifier for the selected serialization."
        },
        "coverage": {
          "type": "string",
          "enum": [
            "full_envelope_and_trades",
            "trades_only"
          ],
          "description": "Sections represented by the artifact. JSON and NDJSON carry the full envelope and trades; CSV carries trade rows only."
        },
        "generation": {
          "$ref": "#/$defs/TraderExportGeneration"
        },
        "row_count": {
          "type": "integer",
          "format": "int64",
          "description": "Number of trade rows written."
        },
        "content_size_bytes": {
          "type": "integer",
          "format": "int64",
          "description": "Exact byte count of the decompressed content stream clients receive."
        },
        "content_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "Lowercase SHA-256 of the decompressed content bytes."
        },
        "compressed_size_bytes": {
          "type": "integer",
          "format": "int64",
          "description": "Exact byte count of the gzip-compressed bytes stored by the object provider."
        },
        "compressed_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "Lowercase SHA-256 of the stored gzip bytes; the multipart ETag is not used as this checksum."
        }
      }
    },
    "TraderExportCategoryWatermark": {
      "type": "object",
      "required": [
        "source",
        "coverage",
        "publication_fence",
        "data_as_of"
      ],
      "properties": {
        "source": {
          "type": "string"
        },
        "coverage": {
          "type": "string"
        },
        "publication_fence": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "data_as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "TraderExportGeneration": {
      "type": "object",
      "required": [
        "id",
        "selected_at",
        "consistency",
        "source_watermarks"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Opaque generation identity selected for the coherent read snapshot."
        },
        "selected_at": {
          "type": "string",
          "format": "date-time"
        },
        "consistency": {
          "type": "string",
          "const": "repeatable_read"
        },
        "source_watermarks": {
          "$ref": "#/$defs/TraderExportSourceWatermarks"
        },
        "product_scope": {
          "type": "string",
          "const": "sports_esports_v1",
          "description": "The markets the file's trades and markets sections hold: sports and esports markets only (export_metadata.scope_note in a JSON or NDJSON file names the sections that still cover every market). Absent on a file written before 2026-10-22, which holds every market; a submit never reuses such a file."
        }
      }
    },
    "TraderExportPnlWatermark": {
      "type": "object",
      "required": [
        "source",
        "coverage",
        "revision",
        "observed_at"
      ],
      "properties": {
        "source": {
          "type": "string"
        },
        "coverage": {
          "type": "string"
        },
        "revision": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64"
        },
        "observed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "TraderExportPositionWatermark": {
      "type": "object",
      "required": [
        "source",
        "coverage",
        "generation",
        "data_as_of"
      ],
      "properties": {
        "source": {
          "type": "string"
        },
        "coverage": {
          "type": "string"
        },
        "generation": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64"
        },
        "data_as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "TraderExportSourceWatermarks": {
      "type": "object",
      "required": [
        "positions",
        "pnl",
        "categories",
        "trades"
      ],
      "properties": {
        "positions": {
          "$ref": "#/$defs/TraderExportPositionWatermark"
        },
        "pnl": {
          "$ref": "#/$defs/TraderExportPnlWatermark"
        },
        "categories": {
          "$ref": "#/$defs/TraderExportCategoryWatermark"
        },
        "trades": {
          "$ref": "#/$defs/TraderExportTradeWatermark"
        }
      }
    },
    "TraderExportTradeWatermark": {
      "type": "object",
      "required": [
        "source",
        "coverage",
        "rows",
        "first_activity_date"
      ],
      "properties": {
        "source": {
          "type": "string"
        },
        "coverage": {
          "type": "string",
          "description": "sports_esports_rows: the file holds every stored trade in the wallet's sports and esports markets. all_matching_rows on a file written before 2026-10-22, which holds every market's trades."
        },
        "rows": {
          "type": "integer",
          "format": "int64",
          "description": "Trade rows the file holds, counted in the same read snapshot as the rows."
        },
        "first_activity_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        }
      }
    }
  }
}