Hello @kvetis,
I’ve used the jobs endpoint quite a bit so I’d be happy to help you out. I agree that the docs could use some work, but I find that is almost always the case (docs can always be improved!)
I’m not sure what all the possible jobs states are, but I am usually only interested in pending, processing, and completed. There’s a failed job as well of course. I usually just iterate on /api/v2/jobs/{id} until I see completed.
I’m not a JSON expert but the resulting file is not, I think, a valid JSON file. Rather each line is a single JSON object representing a single user. Personally I’d prefer if the entire file was formatted as a list object so I can easily slurp it into python. As it stands my scripts iterate over each line, importing each line as an individual JSON object / dict.
limit limits the number of entries in the response. E.g., limit=100 means you will only get back the first 100 results.