Skip to main content
GET
https://app.cometly.com
/
public-api
/
v1
/
contacts
/
exports
/
{id}
Get Contact Export
curl --request GET \
  --url https://app.cometly.com/public-api/v1/contacts/exports/{id} \
  --header 'Authorization: Bearer <token>'
{
  "export_id": 123,
  "status": "<string>",
  "created_at": "<string>",
  "message": "<string>",
  "download_url": "<string>",
  "completed_at": "<string>",
  "expires_at": "<string>"
}

​
Overview

This endpoint retrieves the current status of a contact export job created with the Create Contact Export endpoint. Once the export is complete, it provides a presigned download URL for the exported file. Poll this endpoint regularly to check when your export is ready for download.

​
Path Parameters

​
id
integer
required
The export ID returned from the Create Contact Export endpoint.Example: 123

​
Response

​
Export Status Fields

​
export_id
integer
The unique identifier for this export job
​
status
string
Current status of the export jobPossible values:
  • queued - Export job is waiting to be processed
  • processing - Export is currently being generated
  • completed - Export is complete and ready for download
  • failed - Export failed
​
created_at
string
ISO 8601 timestamp when the export was created
​
message
string
User-friendly status message (present when status is queued, processing, or failed)

​
Additional Fields (When Status = completed)

​
download_url
string
Presigned S3 URL to download the export file. This URL expires after 15 minutes for security.The file is in gzipped NDJSON format (Newline-Delimited JSON, compressed with gzip).
​
completed_at
string
ISO 8601 timestamp when the export finished processing
​
expires_at
string
ISO 8601 timestamp when the download URL will expire (15 minutes from request time)

​
Example Requests

# Check export status
curl -G "https://app.cometly.com/public-api/v1/contacts/exports/123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

​
Example Responses

​
Queued Export

{
  "export_id": 123,
  "status": "queued",
  "created_at": "2024-01-15T10:30:00Z",
  "message": "Export is being processed. Please check back in a few minutes."
}

​
Completed Export

{
  "export_id": 123,
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:33:42Z",
  "download_url": "https://bucket.s3.amazonaws.com/exports/a3f2c8d9-1234-5678-9abc-def012345678.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "expires_at": "2024-01-15T10:48:42Z"
}

​
Failed Export

{
  "export_id": 123,
  "status": "failed",
  "created_at": "2024-01-15T10:30:00Z",
  "message": "Export failed. Please try again in a few minutes. If the problem persists, contact support."
}

​
Status Codes

Status CodeDescription
200Export status retrieved successfully
401Missing or invalid API key
403API key doesn’t have permission or subscription is inactive
404Export not found or belongs to a different space
429Too many requests - rate limit exceeded. See Rate Limiting

​
Notes

  • Rate Limit: This endpoint has a limit of 30 requests per minute per Space. See Rate Limiting for details.
  • Download URL Expiration: The presigned download URL expires 15 minutes after you retrieve it. If it expires, make another GET request to this endpoint to get a fresh URL.
  • Space Isolation: You can only access exports created by your space. Attempting to access another space’s export returns 404.
  • File Security: Export files use UUID-based filenames to prevent enumeration. Download URLs are cryptographically signed and time-limited.
  • Processing Time: Exports typically complete within seconds to a few minutes. Large exports may take longer.

​
See Also